# Veeva Cursor plugin

Use official Veeva Vault platform documentation and optional read-only customer
Vault access from Cursor.

## What it provides

The plugin ships two MCP servers:

1. `vault-docs-mcp` — public documentation search at
   `https://docs.veevavault.dev/mcp`. No authentication.
2. `vault-readonly-mcp` — local stdio MCP that authenticates to a customer Vault
   with OAuth/OIDC and exposes read-only tools.

The docs server searches Vault Platform developer docs, API reference, SDK and
VAPIL Javadocs, and Vault Help. It does not authenticate to a customer Vault.

The customer Vault server can discover OAuth profiles, open a browser login with
PKCE, exchange an IdP access token for a Vault session, run read-only VQL, and
retrieve object/document metadata. It does not create, update, or delete Vault
data, and it does not download source files or renditions.

## Prerequisites for customer Vault auth

Customer administrators must configure:

1. An OAuth/OIDC application in the company identity provider.
2. A Vault OAuth 2.0 / OpenID Connect profile with Authorization Server metadata.
3. Client ID Mapping between the Vault application client ID and the IdP client ID.
4. A loopback redirect URI using `http://127.0.0.1:<port>/callback`. The plugin
   chooses an ephemeral port, so the IdP must allow loopback redirects with a
   dynamic port when possible.

SAML-only security policies without OAuth profiles are out of scope for this
release. Username/password Vault auth is also out of scope.

## Plugin configuration

Set these plugin variables in Cursor Dashboard → Plugins → Configure, or export
them for local development:

| Variable | Required | Purpose |
| --- | --- | --- |
| `VAULT_OAUTH_APP_CLIENT_ID` | Yes | Application Client ID from Vault Client ID Mapping |
| `VAULT_DNS` | No | Preferred Vault hostname, for example `myvault.veevavault.com` |
| `VAULT_OAUTH_SCOPES` | No | Default `openid profile offline_access` |
| `VAULT_API_VERSION` | No | Default `v26.1` |

Cursor's public plugin schema may lag the documented `variables` feature. After
importing into a Team Marketplace, confirm the Configure UI substitutes these
values into `mcp.json`.

## Add it to a Cursor team

1. Open **Cursor Dashboard > Plugins**.
2. Under **Team Marketplaces**, select **Add Marketplace**.
3. Select **Import from Repo** and enter
   `https://github.com/armin-demo/veeva-plugin`.
4. Review the detected plugin and add it to the marketplace.
5. Configure marketplace access, installation mode, optional auto-refresh, and
   the Vault OAuth variables above.

This single-plugin repository does not need a `marketplace.json`.

## Load it for local development

```sh
git clone https://github.com/armin-demo/veeva-plugin.git
cd veeva-plugin
npm install
mkdir -p ~/.cursor/plugins/local
ln -s "$(pwd)" ~/.cursor/plugins/local/veeva
```

Reload Cursor, open **Customize**, and confirm both MCP servers appear.

## Verify the connections

Open Agent chat and enter `/mcp`.

For docs search, ask:

```text
Create Document API request parameters
```

For customer Vault access:

1. Call `discover_vault_auth` with your Vault username.
2. Call `login_vault_oauth` and complete the browser login.
3. Call `vault_connection_status`, then a read tool such as `run_vql`.

Docs query tips are in
[Formatting MCP Queries](https://general.veevavault.dev/mcp/guides/formatting-mcp-queries/).

### Docs MCP tools

- `search_developer_docs`
- `search_api_reference`
- `search_sdk_javadocs`
- `search_vapil_javadocs`
- `search_vault_help_docs`

### Customer Vault MCP tools

- `discover_vault_auth`
- `login_vault_oauth`
- `vault_connection_status`
- `logout_vault`
- `run_vql`
- `get_object_metadata`
- `get_object_record`
- `get_document_metadata`
- `get_document_version_metadata`
- `list_api_versions`

Vault sessions stay in process memory only. Tool responses never include session
IDs, access tokens, or Authorization headers.

## Extend the plugin

| Component | Location |
| --- | --- |
| Skill | `skills/<name>/SKILL.md` |
| Subagent | `agents/<name>.md` |
| Rule | `rules/<name>.mdc` |
| Command | `commands/<name>.md` |
| Hook configuration | `hooks/hooks.json` |
| Shared asset | `assets/` |
| Customer Vault MCP | `servers/vault-readonly/` |

See [CONTRIBUTING.md](CONTRIBUTING.md) for formats, build steps, and secrets
rules.

## Develop and validate

Requires Node.js 18 or newer:

```sh
npm install
npm test
npm run validate
```

The customer Vault MCP entrypoint is a self-contained bundle at
`servers/vault-readonly/dist/index.js`, so marketplace installs do not require
`npm install` on the user machine. Rebuild and commit that bundle after source
changes.

## License and trademarks

The code in this repository is available under the [MIT License](LICENSE).
This is an unofficial community plugin and is not endorsed by Veeva Systems.
Veeva and Vault are trademarks of their respective owner.