@cubis/foundry 0.3.50 → 0.3.52

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 (32) hide show
  1. package/README.md +31 -12
  2. package/bin/cubis.js +662 -80
  3. package/mcp/dist/index.js +108 -46
  4. package/mcp/src/server.ts +51 -39
  5. package/mcp/src/upstream/passthrough.test.ts +30 -0
  6. package/mcp/src/upstream/passthrough.ts +113 -17
  7. package/package.json +1 -1
  8. package/workflows/skills/postman/SKILL.md +76 -7
  9. package/workflows/skills/postman/references/full-mode-setup.md +36 -0
  10. package/workflows/skills/postman/references/troubleshooting.md +25 -0
  11. package/workflows/skills/postman/references/workspace-policy.md +20 -0
  12. package/workflows/workflows/agent-environment-setup/manifest.json +1 -1
  13. package/workflows/workflows/agent-environment-setup/platforms/antigravity/rules/GEMINI.md +10 -1
  14. package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/database.md +1 -1
  15. package/workflows/workflows/agent-environment-setup/platforms/codex/rules/AGENTS.md +10 -1
  16. package/workflows/workflows/agent-environment-setup/platforms/codex/workflows/database.md +1 -1
  17. package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/AGENTS.md +14 -4
  18. package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/copilot-instructions.md +11 -2
  19. package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/SKILL.md +76 -7
  20. package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/references/full-mode-setup.md +36 -0
  21. package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/references/troubleshooting.md +25 -0
  22. package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/references/workspace-policy.md +20 -0
  23. package/workflows/workflows/agent-environment-setup/platforms/copilot/workflows/database.md +1 -1
  24. package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/SKILL.md +76 -7
  25. package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/references/full-mode-setup.md +36 -0
  26. package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/references/troubleshooting.md +25 -0
  27. package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/references/workspace-policy.md +20 -0
  28. package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/SKILL.md +76 -7
  29. package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/references/full-mode-setup.md +36 -0
  30. package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/references/troubleshooting.md +25 -0
  31. package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/references/workspace-policy.md +20 -0
  32. package/workflows/workflows/agent-environment-setup/shared/workflows/database.md +1 -1
@@ -0,0 +1,25 @@
1
+ # Postman MCP Troubleshooting
2
+
3
+ ## Only `postman_get_*` / `postman_set_mode` tools appear
4
+
5
+ 1. Confirm active env alias exists in shell (or persisted env file).
6
+ 2. Sync catalog:
7
+
8
+ ```bash
9
+ cbx mcp tools sync --service postman --scope global
10
+ cbx mcp tools list --service postman --scope global
11
+ ```
12
+
13
+ 3. Restart runtime if using Docker:
14
+
15
+ ```bash
16
+ cbx mcp runtime up --scope global --name cbx-mcp --replace --port 3310
17
+ ```
18
+
19
+ ## Client does not show dotted names
20
+
21
+ Use alias tools (`postman_<tool>`) when dotted names are filtered by client UI.
22
+
23
+ ## Missing API key at startup
24
+
25
+ Expected behavior: tool names can still come from cached catalog; tool calls fail with explicit auth error until env alias is set.
@@ -0,0 +1,20 @@
1
+ # Workspace Default Policy
2
+
3
+ Resolve workspace ID in this order:
4
+
5
+ 1. User-provided workspace ID in the request
6
+ 2. `postman_get_status` default workspace
7
+ 3. Auto-detected workspace when only one exists
8
+ 4. Explicit user selection when multiple workspaces exist
9
+
10
+ ## Persist Selected Workspace
11
+
12
+ ```bash
13
+ cbx workflows config --scope global --workspace-id <workspace-id>
14
+ ```
15
+
16
+ Clear workspace default:
17
+
18
+ ```bash
19
+ cbx workflows config --scope global --clear-workspace-id
20
+ ```
@@ -533,7 +533,7 @@
533
533
  "webapp-testing",
534
534
  "wrangler"
535
535
  ],
536
- "rulesTemplate": "platforms/copilot/rules/AGENTS.md",
536
+ "rulesTemplate": "platforms/copilot/rules/copilot-instructions.md",
537
537
  "hooks": [
538
538
  {
539
539
  "type": "conductor-reference",
@@ -100,6 +100,15 @@ Stop at the earliest step that gives enough signal. Do not jump ahead.
100
100
  4. `skill_get <id>` — load full skill content; only when committed to using it
101
101
  5. `skill_budget_report` — verify token cost after loading; triggers the compact ctx stamp
102
102
 
103
+ ### Postman Intent Trigger (Required)
104
+
105
+ When user intent includes Postman workflows (for example: workspace, collection, environment, runCollection, monitor, mock, or "run Postman tests"):
106
+
107
+ 1. Run `skill_search "postman"` first.
108
+ 2. If `postman` skill exists, load `skill_get "postman"` before workflow/agent routing.
109
+ 3. Prefer Postman MCP tools (`postman.*`) over Newman/CLI fallback unless the user explicitly asks for fallback.
110
+ 4. If `--postman` was installed but `postman` skill cannot be found, report installation drift and suggest reinstall with `cbx workflows install ... --postman`.
111
+
103
112
  **Hard rules:**
104
113
 
105
114
  - Never call `skill_get` without a prior `skill_search` or `skill_browse_category`
@@ -264,7 +273,7 @@ The Foundry MCP server provides progressive-disclosure skill discovery and integ
264
273
  ### Skill Vault
265
274
 
266
275
  - **123** skills across **22** categories
267
- - Estimated full catalog: ~108,488 tokens
276
+ - Estimated full catalog: ~109,067 tokens
268
277
 
269
278
  Categories:
270
279
  - `ai`: 1 skill(s)
@@ -16,7 +16,6 @@ Use this when data modeling, query quality, migration safety, or database perfor
16
16
  - Companion skills: `database-design` (schema/migrations), `database-optimizer` (tuning/triage)
17
17
  - Mobile/local persistence companion: `drift-flutter`
18
18
  - Power bridge: `workflows/powers/database-skills`
19
- - Engine wrappers: `postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`
20
19
 
21
20
  ## Context notes
22
21
  - This workflow file, active platform rules, and selected agents/skills guide execution.
@@ -25,6 +24,7 @@ Use this when data modeling, query quality, migration safety, or database perfor
25
24
  ## Skill Routing
26
25
  - Primary skills: `database-skills`, `database-design`
27
26
  - Supporting skills (optional): `database-optimizer`
27
+ - Engine packs (sub-skills): `database-skills/postgres`, `database-skills/mysql`, `database-skills/vitess`, `database-skills/neki`, `database-skills/mongodb`, `database-skills/sqlite`, `database-skills/supabase`, `database-skills/redis`
28
28
 
29
29
  ## Workflow steps
30
30
  1. Confirm data shape, access patterns, and workload size.
@@ -98,6 +98,15 @@ Stop at the earliest step that gives enough signal. Do not jump ahead.
98
98
  4. `skill_get <id>` — load full skill content; only when committed to using it
99
99
  5. `skill_budget_report` — verify token cost after loading; triggers the compact ctx stamp
100
100
 
101
+ ### Postman Intent Trigger (Required)
102
+
103
+ When user intent includes Postman workflows (for example: workspace, collection, environment, runCollection, monitor, mock, or "run Postman tests"):
104
+
105
+ 1. Run `skill_search "postman"` first.
106
+ 2. If `postman` skill exists, load `skill_get "postman"` before workflow/agent routing.
107
+ 3. Prefer Postman MCP tools (`postman.*`) over Newman/CLI fallback unless the user explicitly asks for fallback.
108
+ 4. If `--postman` was installed but `postman` skill cannot be found, report installation drift and suggest reinstall with `cbx workflows install ... --postman`.
109
+
101
110
  **Hard rules:**
102
111
 
103
112
  - Never call `skill_get` without a prior `skill_search` or `skill_browse_category`
@@ -257,7 +266,7 @@ The Foundry MCP server provides progressive-disclosure skill discovery and integ
257
266
  ### Skill Vault
258
267
 
259
268
  - **123** skills across **22** categories
260
- - Estimated full catalog: ~108,488 tokens
269
+ - Estimated full catalog: ~109,067 tokens
261
270
 
262
271
  Categories:
263
272
  - `ai`: 1 skill(s)
@@ -16,7 +16,6 @@ Use this when data modeling, query quality, migration safety, or database perfor
16
16
  - Companion skills: `database-design` (schema/migrations), `database-optimizer` (tuning/triage)
17
17
  - Mobile/local persistence companion: `drift-flutter`
18
18
  - Power bridge: `workflows/powers/database-skills`
19
- - Engine wrappers: `postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`
20
19
 
21
20
  ## Context notes
22
21
  - This workflow file, active platform rules, and selected agents/skills guide execution.
@@ -25,6 +24,7 @@ Use this when data modeling, query quality, migration safety, or database perfor
25
24
  ## Skill Routing
26
25
  - Primary skills: `database-skills`, `database-design`
27
26
  - Supporting skills (optional): `database-optimizer`
27
+ - Engine packs (sub-skills): `database-skills/postgres`, `database-skills/mysql`, `database-skills/vitess`, `database-skills/neki`, `database-skills/mongodb`, `database-skills/sqlite`, `database-skills/supabase`, `database-skills/redis`
28
28
 
29
29
  ## Workflow steps
30
30
  1. Confirm data shape, access patterns, and workload size.
@@ -1,6 +1,7 @@
1
- # .github/copilot-instructions.md - Cubis Foundry Copilot Protocol
1
+ # AGENTS.md - Copilot Compatibility Bridge
2
2
 
3
- This file defines mandatory behavior for GitHub Copilot projects installed via `cbx workflows`.
3
+ Primary Copilot rule file is `.github/copilot-instructions.md`.
4
+ This `AGENTS.md` exists for cross-tool compatibility (for example Codex/Cursor style readers) and should defer to `.github/copilot-instructions.md` when both files are present.
4
5
 
5
6
  ## 1) Platform Paths
6
7
 
@@ -104,6 +105,15 @@ Stop at the earliest step that gives enough signal. Do not jump ahead.
104
105
  4. `skill_get <id>` — load full skill content; only when committed to using it
105
106
  5. `skill_budget_report` — verify token cost after loading; triggers the compact ctx stamp
106
107
 
108
+ ### Postman Intent Trigger (Required)
109
+
110
+ When user intent includes Postman workflows (for example: workspace, collection, environment, runCollection, monitor, mock, or "run Postman tests"):
111
+
112
+ 1. Run `skill_search "postman"` first.
113
+ 2. If `postman` skill exists, load `skill_get "postman"` before workflow/agent routing.
114
+ 3. Prefer Postman MCP tools (`postman.*`) over Newman/CLI fallback unless the user explicitly asks for fallback.
115
+ 4. If `--postman` was installed but `postman` skill cannot be found, report installation drift and suggest reinstall with `cbx workflows install ... --postman`.
116
+
107
117
  **Hard rules:**
108
118
 
109
119
  - Never call `skill_get` without a prior `skill_search` or `skill_browse_category`
@@ -221,7 +231,7 @@ After loading skills or completing a significant task phase, emit a single compa
221
231
  Use these commands to keep this setup healthy:
222
232
 
223
233
  - Install/update bundle:
224
- `cbx workflows install --platform copilot --bundle agent-environment-setup --scope global --overwrite --postman --stitch --mcp-runtime docker --mcp-fallback local --mcp-tool-sync`
234
+ `cbx workflows install --platform copilot --bundle agent-environment-setup --scope global --overwrite --postman --postman-mode full --stitch --mcp-runtime docker --mcp-fallback local --mcp-tool-sync`
225
235
  - Start MCP Docker runtime:
226
236
  `cbx mcp runtime up --scope global --name cbx-mcp --port 3310 --replace`
227
237
  - Check MCP Docker runtime:
@@ -263,7 +273,7 @@ The Foundry MCP server provides progressive-disclosure skill discovery and integ
263
273
  ### Skill Vault
264
274
 
265
275
  - **123** skills across **22** categories
266
- - Estimated full catalog: ~108,488 tokens
276
+ - Estimated full catalog: ~109,067 tokens
267
277
 
268
278
  Categories:
269
279
  - `ai`: 1 skill(s)
@@ -104,6 +104,15 @@ Stop at the earliest step that gives enough signal. Do not jump ahead.
104
104
  4. `skill_get <id>` — load full skill content; only when committed to using it
105
105
  5. `skill_budget_report` — verify token cost after loading; triggers the compact ctx stamp
106
106
 
107
+ ### Postman Intent Trigger (Required)
108
+
109
+ When user intent includes Postman workflows (for example: workspace, collection, environment, runCollection, monitor, mock, or "run Postman tests"):
110
+
111
+ 1. Run `skill_search "postman"` first.
112
+ 2. If `postman` skill exists, load `skill_get "postman"` before workflow/agent routing.
113
+ 3. Prefer Postman MCP tools (`postman.*`) over Newman/CLI fallback unless the user explicitly asks for fallback.
114
+ 4. If `--postman` was installed but `postman` skill cannot be found, report installation drift and suggest reinstall with `cbx workflows install ... --postman`.
115
+
107
116
  **Hard rules:**
108
117
 
109
118
  - Never call `skill_get` without a prior `skill_search` or `skill_browse_category`
@@ -221,7 +230,7 @@ After loading skills or completing a significant task phase, emit a single compa
221
230
  Use these commands to keep this setup healthy:
222
231
 
223
232
  - Install/update bundle:
224
- `cbx workflows install --platform copilot --bundle agent-environment-setup --scope global --overwrite --postman --stitch --mcp-runtime docker --mcp-fallback local --mcp-tool-sync`
233
+ `cbx workflows install --platform copilot --bundle agent-environment-setup --scope global --overwrite --postman --postman-mode full --stitch --mcp-runtime docker --mcp-fallback local --mcp-tool-sync`
225
234
  - Start MCP Docker runtime:
226
235
  `cbx mcp runtime up --scope global --name cbx-mcp --port 3310 --replace`
227
236
  - Check MCP Docker runtime:
@@ -263,7 +272,7 @@ The Foundry MCP server provides progressive-disclosure skill discovery and integ
263
272
  ### Skill Vault
264
273
 
265
274
  - **123** skills across **22** categories
266
- - Estimated full catalog: ~108,488 tokens
275
+ - Estimated full catalog: ~109,067 tokens
267
276
 
268
277
  Categories:
269
278
  - `ai`: 1 skill(s)
@@ -1,17 +1,86 @@
1
1
  ---
2
2
  name: postman
3
- description: Automate API testing and collection management with Postman MCP. Use for workspace, collection, environment, and mock operations.
3
+ description: Automate API testing and collection management with Postman MCP using full-mode defaults and workspace-aware execution.
4
4
  ---
5
5
 
6
- # Postman MCP
6
+ # Postman MCP Skill
7
7
 
8
- Use this skill when you need to work with Postman through MCP tools.
8
+ Use this skill when you need Postman workspace, collection, environment, or run operations through MCP.
9
9
 
10
- ## Required Environment Variables
10
+ References:
11
+ - [Full-Mode Setup](./references/full-mode-setup.md)
12
+ - [Workspace Policy](./references/workspace-policy.md)
13
+ - [Troubleshooting](./references/troubleshooting.md)
11
14
 
12
- - `POSTMAN_API_KEY_<PROFILE>` for authenticated Postman access.
15
+ ## MCP-First Rule
13
16
 
14
- ## Notes
17
+ - Prefer Postman MCP tools for all Postman operations.
18
+ - Accept both dynamic naming styles from clients:
19
+ - dotted: `postman.<tool>`
20
+ - alias: `postman_<tool>`
21
+ - Do not use Newman/Postman CLI fallback unless the user explicitly asks for fallback.
22
+ - If required Postman MCP tools are unavailable, report discovery/remediation steps first.
23
+
24
+ ## Setup Baseline
25
+
26
+ 1. Install with Postman enabled and explicit full mode:
27
+ - `cbx workflows install --platform <codex|antigravity|copilot> --scope global --bundle agent-environment-setup --postman --postman-mode full --mcp-runtime docker --mcp-fallback local --mcp-tool-sync --yes`
28
+ 2. Persist env aliases once (no per-session re-export):
29
+ - `cbx workflows config keys persist-env --service postman --scope global`
30
+ 3. Verify mode/config:
31
+ - `cbx workflows config --scope global --show`
32
+ - `cbx mcp tools sync --service postman --scope global`
33
+ - `cbx mcp tools list --service postman --scope global`
34
+
35
+ ## Preflight
36
+
37
+ 1. Read Postman status first:
38
+ - Call `postman_get_status`.
39
+ 2. Ensure mode is `full`:
40
+ - If not, call `postman_set_mode` with `mode: full`.
41
+ 3. Discover upstream tools:
42
+ - Confirm required tools exist before execution (for example workspaces/collections/runs).
43
+
44
+ ## Default Workspace Policy
45
+
46
+ Resolve workspace in this order:
47
+
48
+ 1. User-provided workspace ID.
49
+ 2. `postman_get_status.defaultWorkspaceId`.
50
+ 3. Auto-detect from workspace listing:
51
+ - If exactly one workspace exists, use it and state that choice.
52
+ 4. If multiple workspaces and no default:
53
+ - Ask user to choose one.
54
+ - Recommend persisting it with:
55
+ - `cbx workflows config --scope global --workspace-id <workspace-id>`
56
+
57
+ When a Postman tool requires a workspace argument, always pass the resolved workspace ID explicitly.
58
+
59
+ ## Common Workflows
60
+
61
+ ### Collection Run
62
+
63
+ 1. Resolve workspace ID (policy above).
64
+ 2. Resolve `collectionId` and optional `environmentId`.
65
+ 3. Call Postman run tool (`postman.runCollection` or alias equivalent).
66
+ 4. Return a concise run summary:
67
+ - total requests
68
+ - passed/failed tests
69
+ - failing request/test names
70
+ - proposed fix path for failures
71
+
72
+ ## Failure Handling
73
+
74
+ If dynamic Postman tools are missing:
75
+
76
+ 1. Verify env alias expected by config is set.
77
+ 2. Resync catalog:
78
+ - `cbx mcp tools sync --service postman --scope global`
79
+ - `cbx mcp tools list --service postman --scope global`
80
+ 3. Recreate runtime if needed:
81
+ - `cbx mcp runtime up --scope global --name cbx-mcp --replace --port 3310 --skills-root ~/.agents/skills`
82
+
83
+ ## Security Notes
15
84
 
16
85
  - Use environment variables for secrets. Do not inline API keys.
17
- - Prefer tool discovery (`getEnabledTools`) before making assumptions about available tool sets.
86
+ - Never print or persist raw key values in logs, docs, or responses.
@@ -0,0 +1,36 @@
1
+ # Postman Full-Mode Setup
2
+
3
+ Use CLI mode flags instead of manual `jq` edits.
4
+
5
+ ## Install/Upgrade with Full Mode
6
+
7
+ ```bash
8
+ cbx workflows install \
9
+ --platform codex \
10
+ --scope global \
11
+ --bundle agent-environment-setup \
12
+ --postman \
13
+ --postman-mode full \
14
+ --mcp-runtime docker \
15
+ --mcp-fallback local \
16
+ --mcp-tool-sync \
17
+ --overwrite \
18
+ --yes
19
+ ```
20
+
21
+ ## Change Mode Later
22
+
23
+ ```bash
24
+ cbx workflows config --scope global --platform codex --postman-mode full
25
+ ```
26
+
27
+ This updates:
28
+ - `cbx_config.json` Postman URL
29
+ - managed Postman MCP definition under `.cbx/mcp/<platform>/postman.json`
30
+ - platform MCP runtime target patch (when platform is resolvable)
31
+
32
+ ## Persist Env Aliases
33
+
34
+ ```bash
35
+ cbx workflows config keys persist-env --service postman --scope global
36
+ ```
@@ -0,0 +1,25 @@
1
+ # Postman MCP Troubleshooting
2
+
3
+ ## Only `postman_get_*` / `postman_set_mode` tools appear
4
+
5
+ 1. Confirm active env alias exists in shell (or persisted env file).
6
+ 2. Sync catalog:
7
+
8
+ ```bash
9
+ cbx mcp tools sync --service postman --scope global
10
+ cbx mcp tools list --service postman --scope global
11
+ ```
12
+
13
+ 3. Restart runtime if using Docker:
14
+
15
+ ```bash
16
+ cbx mcp runtime up --scope global --name cbx-mcp --replace --port 3310
17
+ ```
18
+
19
+ ## Client does not show dotted names
20
+
21
+ Use alias tools (`postman_<tool>`) when dotted names are filtered by client UI.
22
+
23
+ ## Missing API key at startup
24
+
25
+ Expected behavior: tool names can still come from cached catalog; tool calls fail with explicit auth error until env alias is set.
@@ -0,0 +1,20 @@
1
+ # Workspace Default Policy
2
+
3
+ Resolve workspace ID in this order:
4
+
5
+ 1. User-provided workspace ID in the request
6
+ 2. `postman_get_status` default workspace
7
+ 3. Auto-detected workspace when only one exists
8
+ 4. Explicit user selection when multiple workspaces exist
9
+
10
+ ## Persist Selected Workspace
11
+
12
+ ```bash
13
+ cbx workflows config --scope global --workspace-id <workspace-id>
14
+ ```
15
+
16
+ Clear workspace default:
17
+
18
+ ```bash
19
+ cbx workflows config --scope global --clear-workspace-id
20
+ ```
@@ -16,7 +16,6 @@ Use this when data modeling, query quality, migration safety, or database perfor
16
16
  - Companion skills: `database-design` (schema/migrations), `database-optimizer` (tuning/triage)
17
17
  - Mobile/local persistence companion: `drift-flutter`
18
18
  - Power bridge: `workflows/powers/database-skills`
19
- - Engine wrappers: `postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`
20
19
 
21
20
  ## Context notes
22
21
  - This workflow file, active platform rules, and selected agents/skills guide execution.
@@ -25,6 +24,7 @@ Use this when data modeling, query quality, migration safety, or database perfor
25
24
  ## Skill Routing
26
25
  - Primary skills: `database-skills`, `database-design`
27
26
  - Supporting skills (optional): `database-optimizer`
27
+ - Engine packs (sub-skills): `database-skills/postgres`, `database-skills/mysql`, `database-skills/vitess`, `database-skills/neki`, `database-skills/mongodb`, `database-skills/sqlite`, `database-skills/supabase`, `database-skills/redis`
28
28
 
29
29
  ## Workflow steps
30
30
  1. Confirm data shape, access patterns, and workload size.
@@ -1,17 +1,86 @@
1
1
  ---
2
2
  name: postman
3
- description: Automate API testing and collection management with Postman MCP. Use for workspace, collection, environment, and mock operations.
3
+ description: Automate API testing and collection management with Postman MCP using full-mode defaults and workspace-aware execution.
4
4
  ---
5
5
 
6
- # Postman MCP
6
+ # Postman MCP Skill
7
7
 
8
- Use this skill when you need to work with Postman through MCP tools.
8
+ Use this skill when you need Postman workspace, collection, environment, or run operations through MCP.
9
9
 
10
- ## Required Environment Variables
10
+ References:
11
+ - [Full-Mode Setup](./references/full-mode-setup.md)
12
+ - [Workspace Policy](./references/workspace-policy.md)
13
+ - [Troubleshooting](./references/troubleshooting.md)
11
14
 
12
- - `POSTMAN_API_KEY_<PROFILE>` for authenticated Postman access.
15
+ ## MCP-First Rule
13
16
 
14
- ## Notes
17
+ - Prefer Postman MCP tools for all Postman operations.
18
+ - Accept both dynamic naming styles from clients:
19
+ - dotted: `postman.<tool>`
20
+ - alias: `postman_<tool>`
21
+ - Do not use Newman/Postman CLI fallback unless the user explicitly asks for fallback.
22
+ - If required Postman MCP tools are unavailable, report discovery/remediation steps first.
23
+
24
+ ## Setup Baseline
25
+
26
+ 1. Install with Postman enabled and explicit full mode:
27
+ - `cbx workflows install --platform <codex|antigravity|copilot> --scope global --bundle agent-environment-setup --postman --postman-mode full --mcp-runtime docker --mcp-fallback local --mcp-tool-sync --yes`
28
+ 2. Persist env aliases once (no per-session re-export):
29
+ - `cbx workflows config keys persist-env --service postman --scope global`
30
+ 3. Verify mode/config:
31
+ - `cbx workflows config --scope global --show`
32
+ - `cbx mcp tools sync --service postman --scope global`
33
+ - `cbx mcp tools list --service postman --scope global`
34
+
35
+ ## Preflight
36
+
37
+ 1. Read Postman status first:
38
+ - Call `postman_get_status`.
39
+ 2. Ensure mode is `full`:
40
+ - If not, call `postman_set_mode` with `mode: full`.
41
+ 3. Discover upstream tools:
42
+ - Confirm required tools exist before execution (for example workspaces/collections/runs).
43
+
44
+ ## Default Workspace Policy
45
+
46
+ Resolve workspace in this order:
47
+
48
+ 1. User-provided workspace ID.
49
+ 2. `postman_get_status.defaultWorkspaceId`.
50
+ 3. Auto-detect from workspace listing:
51
+ - If exactly one workspace exists, use it and state that choice.
52
+ 4. If multiple workspaces and no default:
53
+ - Ask user to choose one.
54
+ - Recommend persisting it with:
55
+ - `cbx workflows config --scope global --workspace-id <workspace-id>`
56
+
57
+ When a Postman tool requires a workspace argument, always pass the resolved workspace ID explicitly.
58
+
59
+ ## Common Workflows
60
+
61
+ ### Collection Run
62
+
63
+ 1. Resolve workspace ID (policy above).
64
+ 2. Resolve `collectionId` and optional `environmentId`.
65
+ 3. Call Postman run tool (`postman.runCollection` or alias equivalent).
66
+ 4. Return a concise run summary:
67
+ - total requests
68
+ - passed/failed tests
69
+ - failing request/test names
70
+ - proposed fix path for failures
71
+
72
+ ## Failure Handling
73
+
74
+ If dynamic Postman tools are missing:
75
+
76
+ 1. Verify env alias expected by config is set.
77
+ 2. Resync catalog:
78
+ - `cbx mcp tools sync --service postman --scope global`
79
+ - `cbx mcp tools list --service postman --scope global`
80
+ 3. Recreate runtime if needed:
81
+ - `cbx mcp runtime up --scope global --name cbx-mcp --replace --port 3310 --skills-root ~/.agents/skills`
82
+
83
+ ## Security Notes
15
84
 
16
85
  - Use environment variables for secrets. Do not inline API keys.
17
- - Prefer tool discovery (`getEnabledTools`) before making assumptions about available tool sets.
86
+ - Never print or persist raw key values in logs, docs, or responses.
@@ -0,0 +1,36 @@
1
+ # Postman Full-Mode Setup
2
+
3
+ Use CLI mode flags instead of manual `jq` edits.
4
+
5
+ ## Install/Upgrade with Full Mode
6
+
7
+ ```bash
8
+ cbx workflows install \
9
+ --platform codex \
10
+ --scope global \
11
+ --bundle agent-environment-setup \
12
+ --postman \
13
+ --postman-mode full \
14
+ --mcp-runtime docker \
15
+ --mcp-fallback local \
16
+ --mcp-tool-sync \
17
+ --overwrite \
18
+ --yes
19
+ ```
20
+
21
+ ## Change Mode Later
22
+
23
+ ```bash
24
+ cbx workflows config --scope global --platform codex --postman-mode full
25
+ ```
26
+
27
+ This updates:
28
+ - `cbx_config.json` Postman URL
29
+ - managed Postman MCP definition under `.cbx/mcp/<platform>/postman.json`
30
+ - platform MCP runtime target patch (when platform is resolvable)
31
+
32
+ ## Persist Env Aliases
33
+
34
+ ```bash
35
+ cbx workflows config keys persist-env --service postman --scope global
36
+ ```
@@ -0,0 +1,25 @@
1
+ # Postman MCP Troubleshooting
2
+
3
+ ## Only `postman_get_*` / `postman_set_mode` tools appear
4
+
5
+ 1. Confirm active env alias exists in shell (or persisted env file).
6
+ 2. Sync catalog:
7
+
8
+ ```bash
9
+ cbx mcp tools sync --service postman --scope global
10
+ cbx mcp tools list --service postman --scope global
11
+ ```
12
+
13
+ 3. Restart runtime if using Docker:
14
+
15
+ ```bash
16
+ cbx mcp runtime up --scope global --name cbx-mcp --replace --port 3310
17
+ ```
18
+
19
+ ## Client does not show dotted names
20
+
21
+ Use alias tools (`postman_<tool>`) when dotted names are filtered by client UI.
22
+
23
+ ## Missing API key at startup
24
+
25
+ Expected behavior: tool names can still come from cached catalog; tool calls fail with explicit auth error until env alias is set.
@@ -0,0 +1,20 @@
1
+ # Workspace Default Policy
2
+
3
+ Resolve workspace ID in this order:
4
+
5
+ 1. User-provided workspace ID in the request
6
+ 2. `postman_get_status` default workspace
7
+ 3. Auto-detected workspace when only one exists
8
+ 4. Explicit user selection when multiple workspaces exist
9
+
10
+ ## Persist Selected Workspace
11
+
12
+ ```bash
13
+ cbx workflows config --scope global --workspace-id <workspace-id>
14
+ ```
15
+
16
+ Clear workspace default:
17
+
18
+ ```bash
19
+ cbx workflows config --scope global --clear-workspace-id
20
+ ```