@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.
- package/README.md +31 -12
- package/bin/cubis.js +662 -80
- package/mcp/dist/index.js +108 -46
- package/mcp/src/server.ts +51 -39
- package/mcp/src/upstream/passthrough.test.ts +30 -0
- package/mcp/src/upstream/passthrough.ts +113 -17
- package/package.json +1 -1
- package/workflows/skills/postman/SKILL.md +76 -7
- package/workflows/skills/postman/references/full-mode-setup.md +36 -0
- package/workflows/skills/postman/references/troubleshooting.md +25 -0
- package/workflows/skills/postman/references/workspace-policy.md +20 -0
- package/workflows/workflows/agent-environment-setup/manifest.json +1 -1
- package/workflows/workflows/agent-environment-setup/platforms/antigravity/rules/GEMINI.md +10 -1
- package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/database.md +1 -1
- package/workflows/workflows/agent-environment-setup/platforms/codex/rules/AGENTS.md +10 -1
- package/workflows/workflows/agent-environment-setup/platforms/codex/workflows/database.md +1 -1
- package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/AGENTS.md +14 -4
- package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/copilot-instructions.md +11 -2
- package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/SKILL.md +76 -7
- package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/references/full-mode-setup.md +36 -0
- package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/references/troubleshooting.md +25 -0
- package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/references/workspace-policy.md +20 -0
- package/workflows/workflows/agent-environment-setup/platforms/copilot/workflows/database.md +1 -1
- package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/SKILL.md +76 -7
- package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/references/full-mode-setup.md +36 -0
- package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/references/troubleshooting.md +25 -0
- package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/references/workspace-policy.md +20 -0
- package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/SKILL.md +76 -7
- package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/references/full-mode-setup.md +36 -0
- package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/references/troubleshooting.md +25 -0
- package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/references/workspace-policy.md +20 -0
- 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
|
+
```
|
|
@@ -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: ~
|
|
276
|
+
- Estimated full catalog: ~109,067 tokens
|
|
268
277
|
|
|
269
278
|
Categories:
|
|
270
279
|
- `ai`: 1 skill(s)
|
package/workflows/workflows/agent-environment-setup/platforms/antigravity/workflows/database.md
CHANGED
|
@@ -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: ~
|
|
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
|
-
# .
|
|
1
|
+
# AGENTS.md - Copilot Compatibility Bridge
|
|
2
2
|
|
|
3
|
-
|
|
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: ~
|
|
276
|
+
- Estimated full catalog: ~109,067 tokens
|
|
267
277
|
|
|
268
278
|
Categories:
|
|
269
279
|
- `ai`: 1 skill(s)
|
package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/copilot-instructions.md
CHANGED
|
@@ -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: ~
|
|
275
|
+
- Estimated full catalog: ~109,067 tokens
|
|
267
276
|
|
|
268
277
|
Categories:
|
|
269
278
|
- `ai`: 1 skill(s)
|
package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/postman/SKILL.md
CHANGED
|
@@ -1,17 +1,86 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: postman
|
|
3
|
-
description: Automate API testing and collection management with Postman MCP
|
|
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
|
|
8
|
+
Use this skill when you need Postman workspace, collection, environment, or run operations through MCP.
|
|
9
9
|
|
|
10
|
-
|
|
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
|
-
-
|
|
15
|
+
## MCP-First Rule
|
|
13
16
|
|
|
14
|
-
|
|
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
|
-
-
|
|
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.
|
package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/SKILL.md
CHANGED
|
@@ -1,17 +1,86 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: postman
|
|
3
|
-
description: Automate API testing and collection management with Postman MCP
|
|
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
|
|
8
|
+
Use this skill when you need Postman workspace, collection, environment, or run operations through MCP.
|
|
9
9
|
|
|
10
|
-
|
|
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
|
-
-
|
|
15
|
+
## MCP-First Rule
|
|
13
16
|
|
|
14
|
-
|
|
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
|
-
-
|
|
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
|
+
```
|