-
Notifications
You must be signed in to change notification settings - Fork 3
Add MCP integration and Developer Environments skill (v1.2.0) #6
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+362
−14
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| .DS_Store | ||
|
|
||
| # Environment files (keep templates committable) | ||
| .env | ||
| .env.* | ||
| !.env.example | ||
| !.env.sample | ||
| !.env.template | ||
| !.env.dist | ||
|
|
||
| # Python | ||
| __pycache__/ | ||
| *.py[cod] | ||
|
|
||
| # Local dev hook wiring (use when team policy blocks local plugin imports) | ||
| .cursor/hooks.json |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| { | ||
| "mcpServers": { | ||
| "1password": { | ||
| "command": "1password-mcp", | ||
| "args": [] | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,145 @@ | ||
| --- | ||
| name: 1password-environments | ||
| description: >- | ||
| Manage 1Password Developer Environments via the bundled MCP server. Use when | ||
| creating, importing, or mounting .env files; listing Environment variable names; | ||
| adding or updating Environment variables; renaming environments; or calling any | ||
| 1Password MCP tool. Import-from-.env always includes create_local_env_file at | ||
| the source .env path unless the user explicitly opts out of mounting. | ||
| --- | ||
|
|
||
| # 1Password Environments | ||
|
|
||
| Workflow for the 1Password MCP tools bundled with this plugin. Read this skill | ||
| before calling MCP tools — the MCP server's built-in docs cover tool basics but | ||
| omit import-and-mount steps. Conceptual background and edge cases: | ||
| [reference.md](reference.md). | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - **macOS or Linux** with the 1Password desktop app installed (MCP, local `.env` mounts, and mount validation are not supported on Windows) | ||
| - **MCP Server** Labs experiment enabled in the desktop app (`onepassword://settings/labs`) | ||
| - Plugin installed (registers `1password-mcp` MCP config, this skill, and mount validation hooks together) | ||
|
|
||
| Setup details: [reference.md](reference.md) | ||
|
|
||
| ## Not done until | ||
|
|
||
| **Import / create from `.env`** (including "using values from the project `.env`"): | ||
|
|
||
| - [ ] Environment created or resolved | ||
| - [ ] Variables appended via `append_variables` | ||
| - [ ] `create_local_env_file` at the **source** `.env` absolute path — **always** | ||
| - [ ] Mount verified with `list_local_env_files` | ||
|
|
||
| Mounting at the source `.env` path is mandatory, not optional follow-up. The | ||
| **only** exception is the user explicitly opting out ("without mounting", "do not | ||
| mount", "skip the mount"). Never ask "want me to mount?" — just mount. | ||
|
|
||
| Stopping after `create_environment` + `append_variables` is **incomplete**. | ||
| `list_variables` is not mount verification. Do not report success until the mount | ||
| checklist is done. | ||
|
|
||
| **Mount only:** mount exists at the requested path (`list_local_env_files`). | ||
|
|
||
| ## Do not | ||
|
|
||
| - Skip `create_local_env_file` on import unless the user explicitly opted out | ||
| - Report success before the import checklist (including mount) is complete | ||
| - Offer mounting as optional follow-up — it is mandatory on import | ||
| - Call `create_environment` when `list_environments` already shows that name — ask the user first (see **Duplicate environment name**) | ||
| - Reveal secret values in chat | ||
| - Read a mounted `.env` path — once mounted, the path is a live FIFO (named pipe); use `list_variables` instead | ||
|
|
||
| ## MCP tools | ||
|
|
||
| Discover tool schemas for `plugin-1password-1password` before invoking tools | ||
| (`GetMcpTools`, MCP tool descriptors, or equivalent). | ||
|
|
||
| Request params use **camelCase** (`accountId`, `environmentId`); responses may use | ||
| snake_case (`account_id`, `environment_id`). Pass every required param. | ||
|
|
||
| Non-obvious schema details: | ||
|
|
||
| - `create_local_env_file`: `mountPath` must be the **absolute** path of the source `.env` file (macOS/Linux) | ||
| - Environment-level tools may prompt the user for per-environment approval on first use | ||
|
|
||
| If MCP calls fail with authentication errors, call `authenticate`, then retry with | ||
| the returned account ID (use as `accountId` in subsequent calls). | ||
|
|
||
| ## Resolve environment | ||
|
|
||
| After `authenticate` → `list_environments`: | ||
|
|
||
| 1. Match `environmentName` exactly (case-sensitive) to get `environmentId` | ||
| 2. If no match, ask the user for the correct name — do not guess | ||
| 3. If multiple accounts/environments confuse the match, list names only and ask | ||
|
|
||
| ## Duplicate environment name | ||
|
|
||
| Before **`create_environment`**, call **`list_environments`** and check whether the | ||
| target `environmentName` already exists. | ||
|
|
||
| If it does, **stop and ask the user** how they want to proceed. Offer options such as: | ||
|
|
||
| - **Use the existing environment** — skip `create_environment`; use its `environmentId` for later steps (`append_variables`, mount, etc.) | ||
| - **Use a different name** — wait for a new name from the user, then `create_environment` | ||
| - **Cancel** — do not create or modify anything | ||
|
|
||
| Do not silently choose one of these paths. Do not call `create_environment` with a | ||
| name that already exists unless the user has explicitly chosen a different name. | ||
|
|
||
| ## Import from a `.env` file | ||
|
|
||
| Default path: `{workspace_root}/.env` unless the user names another path. | ||
|
|
||
| 1. **Read** the `.env` file with the Read tool to get its keys and values. Strip optional surrounding quotes from values. Pass values to MCP only — never paste secret values into chat. | ||
| 2. **`authenticate`** → `accountId` | ||
| 3. **`list_environments`** — if the target name already exists, follow **Duplicate environment name** and wait for the user's choice. Otherwise **`create_environment`** (new name) or resolve the existing environment per the user's choice. | ||
| 4. **`append_variables`** with all variables (see **Concealed variables**) | ||
| 5. **Mount** — **always** (skip only if the user explicitly said not to mount): | ||
| - If the `.env` is **git-tracked**, stop and tell the user to delete it and commit that removal before mounting ([local .env file docs](https://www.1password.dev/environments/local-env-file.md)) | ||
| - `list_local_env_files` — skip `create_local_env_file` only if a mount already exists at the source path | ||
| - `create_local_env_file` with `accountId`, `environmentId`, `environmentName`, `mountPath` (absolute path of the original `.env`) | ||
| - `list_local_env_files` again to verify | ||
|
|
||
| If shell commands are blocked because 1Password expects a mount at the path, see | ||
| [reference.md](reference.md) (mount conflict). | ||
|
|
||
| ## Other flows | ||
|
|
||
| **Create new Environment:** authenticate → `list_environments` → if the name exists, follow **Duplicate environment name** → `create_environment` only when the name is available or the user chose a different name. | ||
|
|
||
| **Mount existing Environment:** authenticate → resolve environment → step 5 above. | ||
|
|
||
| **Inspect names:** authenticate → resolve environment → `list_variables` → summarize names only. | ||
|
|
||
| **Rename:** authenticate → resolve environment → confirm name → `rename_environment`. | ||
|
|
||
| **Add/update variables:** authenticate → resolve environment → `list_variables` → `append_variables`. | ||
|
|
||
| ## Concealed variables | ||
|
|
||
| When calling `append_variables`, set `concealed` per variable: | ||
|
|
||
| - Set `concealed: true` for API keys, tokens, passwords, private keys, and connection strings with credentials. | ||
| - Set `concealed: false` for ports, public URLs, feature flags, and non-sensitive config unless the user says otherwise. | ||
| - When unsure, default to `concealed: true`. | ||
|
|
||
| ## Safety | ||
|
|
||
| - Never reveal secret values in chat | ||
| - Ask before changing variables unless the request is explicit | ||
|
|
||
| ## Plugin hook | ||
|
|
||
| The plugin runs `validate-mounted-env-files` on `beforeShellExecution`. It blocks | ||
| shell commands when 1Password expects a mount that is missing, disabled, or not a | ||
| FIFO (for example a plain `.env` still on disk at the mount path). Reading the | ||
| `.env` with the Read tool is unaffected. | ||
|
|
||
| Validation modes and recovery steps: [reference.md](reference.md) | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| Mount conflict, validation modes, setup: [reference.md](reference.md) |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@rishiy15 if I am reading OS-267 correctly, we actually need to omit this, right?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this only matters if we named the skills directory something else. The docs state:
So as of now, it is a no-op since the folder name specified is the default name. I do not have a strong preference for either keeping or removing it.