### Test Resolver with Example Config File

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Tests the OCI Vault Resolver script using a provided example configuration file (`test-mcp-config.yaml`). Supports verbose logging and dry run options.

```bash
cd ~/projects/oci-vault-mcp-resolver

# Test with the example config
python3 oci_vault_resolver.py -i test-mcp-config.yaml

# Test with verbose logging
python3 oci_vault_resolver.py -i test-mcp-config.yaml --verbose

# Dry run to preview
cat test-mcp-config.yaml | python3 oci_vault_resolver.py
```

--------------------------------

### Systemd Service for MCP Gateway

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

An example configuration for a systemd service that runs the MCP Gateway with OCI Vault secrets. This ensures the gateway starts automatically on boot and after network availability.

```bash
# /etc/systemd/system/mcp-gateway.service
[Unit]
Description=Docker MCP Gateway with OCI Vault Secrets
After=network.target

[Service]
Type=oneshot
ExecStart=/home/alex/projects/oci-vault-mcp-resolver/mcp-with-vault --start
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Troubleshoot OCI CLI Configuration

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Provides the command to configure the OCI CLI if it is not already set up. This is a prerequisite for interacting with OCI services.

```bash
# Configure OCI CLI
oci setup config
```

--------------------------------

### YAML Example: Direct OCID Secret Reference

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Example of referencing an OCI Vault secret using its direct OCID. This method is fast but less portable as OCIDs are environment-specific.

```yaml
MY_SECRET: oci-vault://ocid1.vaultsecret.oc1.eu-frankfurt-1.amaaaaaahhxc6pyanshr7dq5klnc4mld6otcwzz3ijkkbbrwamk6kx7vb7wq
```

--------------------------------

### Read MCP Configuration

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Reads the current MCP configuration. This is typically the first step before modifying or applying configuration changes.

```bash
docker mcp config read
```

--------------------------------

### Troubleshoot OCI SDK Installation

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

This bash script provides instructions for installing the OCI Python SDK, which is a prerequisite for the resolver. It recommends installing from `requirements.txt` but also offers direct installation via pip. It includes a verification step to confirm the SDK is installed correctly.

```bash
# Install from requirements.txt (recommended)
pip3 install --user -r requirements.txt

# Or install SDK directly
pip3 install --user oci PyYAML

# Verify installation
python3 -c "import oci; print(oci.__version__)"
```

--------------------------------

### Enable Verbose Mode for Debugging

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Enables verbose logging output for the `mcp-with-vault` script, providing detailed debug information to aid in troubleshooting.

```bash
# See detailed debug output
./mcp-with-vault --verbose
```

--------------------------------

### Install OCI SDK and Dependencies

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

Provides instructions for installing the necessary Python packages for the OCI Vault MCP Resolver. It includes commands for installing all dependencies from a `requirements.txt` file or installing the core `oci` and `PyYAML` libraries manually using pip.

```bash
# Install OCI SDK and dependencies
pip install -r requirements.txt

# Or install manually
pip install oci PyYAML
```

--------------------------------

### Start Application with Resolved Configuration

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

After resolving secrets using the `oci_vault_resolver.py` script, this command shows how to start an application (e.g., `app.py`) using the newly created configuration file that contains the resolved secrets. This ensures the application runs with the necessary sensitive values available.

```bash
# Start the application using the resolved configuration file
$ python app.py --config config/app-resolved.yaml
```

--------------------------------

### Install OCI SDK - Troubleshooting Step

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/SDK_IMPLEMENTATION.md

Provides the command to install the OCI SDK, a common solution for 'SDK Not Available' or 'SDK Import Error' troubleshooting scenarios.

```bash
pip install oci
```

--------------------------------

### YAML Example: Vault + Name Secret Reference

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Example of referencing an OCI Vault secret using its Vault OCID and name. This method scopes the secret to a specific vault and is useful in multi-vault environments.

```yaml
MY_SECRET: oci-vault://ocid1.vault.oc1.eu-frankfurt-1.xxx/mcp-test-secret
```

--------------------------------

### CLI Reference - test-setup.sh

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/API_REFERENCE.md

Interactive setup and testing script for OCI Vault MCP Resolver.

```APIDOC
## CLI Reference - test-setup.sh

Interactive setup and testing script.

### Synopsis

```bash
./test-setup.sh
```

### Method

`CLI`

### Endpoint

`./test-setup.sh`

### Parameters

#### Query Parameters

None

#### Interactive Prompts

- Create test secret? (y/N)
- Compartment OCID
- Vault name (if creating)
- Secret name
- Secret value

### Response

#### Success Response (0)

- Code 0: All checks passed

#### Error Response (1)

- Code 1: Missing dependency or configuration issue
```

--------------------------------

### Restart MCP Gateway

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Restarts the MCP Gateway service. This might be necessary after configuration changes to ensure the new settings are applied.

```bash
docker mcp gateway restart
```

--------------------------------

### Troubleshoot Failed Secret Fetch

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Offers commands to diagnose issues when failing to fetch secrets. It includes testing direct OCI CLI secret retrieval and checking IAM permissions for the user.

```bash
# Test OCI CLI directly
oci secrets secret-bundle get --secret-id YOUR_SECRET_OCID

# Check IAM permissions
oci iam user get --user-id YOUR_USER_OCID
```

--------------------------------

### YAML Example: Compartment + Name Secret Reference

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Example of referencing an OCI Vault secret using its compartment OCID and name. This method is recommended for portability and self-documentation, though it involves two API calls on a cache miss.

```yaml
MY_SECRET: oci-vault://ocid1.compartment.oc1..aaaaaaaarekfofhmfup6d33agbnicuop2waas3ssdwdc7qjgencirdgvl3iq/mcp-test-secret
```

--------------------------------

### Initialize Distributed Cache with Redis

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/SDK_IMPLEMENTATION.md

A Python example showing the initialization of a distributed cache using Redis, enabling cache sharing across instances.

```python
# Share cache across instances
import redis
cache = redis.Redis(...)
```

--------------------------------

### test-setup.sh Script Execution

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/API_REFERENCE.md

Illustrates the execution of the `test-setup.sh` script, which is an interactive utility for setting up and testing the OCI Vault MCP Resolver. The script checks for necessary dependencies (Python, PyYAML, OCI CLI, Docker MCP), verifies OCI CLI authentication, lists available OCI resources, and optionally guides the user through creating a test secret.

```bash
./test-setup.sh
```

--------------------------------

### Manage Cache Directory

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Provides commands for managing the OCI Vault MCP resolver's cache, including viewing cached secrets, clearing the entire cache, and checking the age of cached files.

```bash
# View cached secrets
ls -lah ~/.cache/oci-vault-mcp/

# Clear all cache
rm -rf ~/.cache/oci-vault-mcp/

# View cache age
stat ~/.cache/oci-vault-mcp/*.json
```

--------------------------------

### Bash Scripting Best Practices

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/CONTRIBUTING.md

This Bash example demonstrates recommended practices such as using `set -euo pipefail`, quoting variables, and encapsulating reusable logic within functions for clarity and robustness.

```bash
# Good
check_dependency() {
    local cmd="$1"
    if ! command -v "$cmd" &> /dev/null;
        echo "ERROR: $cmd not found"
        return 1
    fi
}

# Use it
check_dependency "python3"
```

--------------------------------

### Installing OCI SDK Dependencies

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/SDK_IMPLEMENTATION.md

Provides instructions for installing the necessary Python dependencies for the OCI Vault Resolver, including the OCI SDK and PyYAML, using pip.

```bash
# Install all dependencies including SDK
pip install -r requirements.txt

# Or install individually
pip install oci PyYAML

# Configure authentication
oci setup config  # For config file auth
# OR use --instance-principals flag on OCI VMs
```

--------------------------------

### Configure Multiple Services with OCI Vault Secrets

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

This example illustrates configuring multiple services (database and API) with secrets from OCI Vault. It showcases referencing secrets by OCID for database passwords and API keys, and by compartment and secret name for webhook secrets. This allows for granular secret management per service.

```yaml
servers:
  database:
    config:
      DB_HOST: postgres.example.com
      DB_USER: admin
      DB_PASSWORD: oci-vault://ocid1.compartment.oc1..xxx/db-password

  api:
    config:
      API_KEY: oci-vault://ocid1.compartment.oc1..xxx/api-key
      WEBHOOK_SECRET: oci-vault://ocid1.vaultsecret.oc1.iad.yyy
```

--------------------------------

### Troubleshoot Stale Cache

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Provides instructions to clear the local cache and re-fetch secrets when the cache is outdated. This is often necessary after updating secrets in OCI Vault.

```bash
# Clear cache and retry
rm -rf ~/.cache/oci-vault-mcp/
./mcp-with-vault
```

--------------------------------

### Systemd Service Configuration

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/API_REFERENCE.md

Example of a systemd service file for integrating the MCP Gateway with OCI Vault secrets. Ensures the service starts after the network is available.

```ini
[Unit]
Description=MCP Gateway with OCI Vault Secrets
After=network.target

[Service]
Type=oneshot
ExecStart=/path/to/mcp-with-vault --start
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Use OCI Vault Resolver from Command Line (Bash)

Source: https://context7.com/acedergren/oci-vault-mcp-resolver/llms.txt

Provides examples of how to use the OCI Vault MCP Resolver script from the command line. It covers piping configurations through stdin/stdout, reading from and writing to files, and enabling verbose logging.

```bash
# Basic usage: resolve secrets in config and output to stdout
docker mcp config read | python3 oci_vault_resolver.py | docker mcp config write

# Read from file, write to file
python3 oci_vault_resolver.py -i config.yaml -o resolved-config.yaml

# Enable verbose logging to stderr
python3 oci_vault_resolver.py -i config.yaml --verbose 2>&1 | tee resolution.log
```

--------------------------------

### Apply MCP Configuration Changes

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Applies modified MCP configuration changes. This involves reading the current config, editing it (e.g., to add vault references), and then writing the updated config back.

```bash
docker mcp config read > /tmp/mcp-config.yaml
# Edit /tmp/mcp-config.yaml to add vault references
cat /tmp/mcp-config.yaml | docker mcp config write
```

--------------------------------

### Authentication with Config File

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/SDK_IMPLEMENTATION.md

Shows examples of how to use the OCI Vault Resolver with a configuration file, including specifying custom profiles and custom config file locations.

```bash
# Uses ~/.oci/config
python3 oci_vault_resolver.py -i config.yaml -o resolved.yaml

# Custom profile
python3 oci_vault_resolver.py --profile PRODUCTION -i config.yaml

# Custom config file
python3 oci_vault_resolver.py --config-file /path/to/config -i config.yaml
```

--------------------------------

### Perform a Dry Run

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Executes the `mcp-with-vault` script in dry run mode, allowing you to preview which secrets would be resolved without actually applying the changes.

```bash
# Preview what would be resolved
./mcp-with-vault --dry-run
```

--------------------------------

### Clone Repository and Install Dependencies (Bash)

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/CONTRIBUTING.md

This snippet demonstrates how to clone the project repository, navigate into the directory, and install the necessary Python dependencies using pip. It ensures your development environment is set up correctly.

```bash
git clone https://github.com/YOUR_USERNAME/oci-vault-mcp-resolver.git
cd oci-vault-mcp-resolver
pip install PyYAML
```

--------------------------------

### Test OCI SDK Configuration and Permissions

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

This Python script is used to test your OCI SDK configuration and ensure you have the necessary permissions to fetch secrets. It attempts to retrieve a secret bundle using your default OCI configuration. Successful execution indicates proper setup.

```python
import oci
config = oci.config.from_file()
from oci.secrets import SecretsClient
client = SecretsClient(config)
bundle = client.get_secret_bundle(secret_id='<secret-ocid>')
print('Success!')
```

--------------------------------

### Resolve Secrets with Wrapper Script

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Uses a recommended wrapper script to resolve secrets within the MCP configuration. This script likely automates the process of reading the config, resolving vault references using the OCI Vault MCP Resolver, and writing the resolved config.

```bash
cd ~/projects/oci-vault-mcp-resolver
./mcp-with-vault
```

--------------------------------

### Wrapper Script with Combined Options

Source: https://context7.com/acedergren/oci-vault-mcp-resolver/llms.txt

Demonstrates using multiple options with the MCP Gateway integration wrapper script, including custom cache TTL, verbose output, and starting the gateway. This showcases the flexibility of the wrapper script.

```bash
./mcp-with-vault --ttl 3600 --verbose --start
```

--------------------------------

### Python Code Style Example

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/CONTRIBUTING.md

This Python code snippet showcases good practices according to PEP 8, including type hints and descriptive naming. It contrasts with an example of less readable code to highlight preferred style.

```python
# Good
def fetch_secret_by_ocid(self, secret_ocid: str) -> Optional[str]:
    """Fetch secret value from OCI Vault by secret OCID."""
    pass

# Avoid
def get(self, x):
    pass
```

--------------------------------

### Get Specific Secret Version with OCI SDK

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/SDK_IMPLEMENTATION.md

A Python code example demonstrating how to retrieve a specific version of a secret bundle using the OCI SDK's `get_secret_bundle` method.

```python
# Get specific secret version
response = client.get_secret_bundle(
    secret_id=ocid,
    version_number=2
)
```

--------------------------------

### Integrate OCI Vault Resolver in GitHub Actions (YAML)

Source: https://context7.com/acedergren/oci-vault-mcp-resolver/llms.txt

Example of how to integrate the OCI Vault Resolver into a GitHub Actions workflow. This involves checking out code, setting up Python, installing dependencies, configuring OCI credentials, resolving secrets using the resolver script, deploying the application, and cleaning up resolved secrets.

```yaml
# GitHub Actions example
name: Deploy with OCI Vault Secrets

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          pip install -r requirements.txt

      - name: Configure OCI credentials
        run: |
          mkdir -p ~/.oci
          echo "${{ secrets.OCI_CONFIG }}" > ~/.oci/config
          echo "${{ secrets.OCI_KEY }}" > ~/.oci/key.pem
          chmod 600 ~/.oci/key.pem

      - name: Resolve secrets
        run: |
          python3 oci_vault_resolver.py \
            -i deployment/config.yaml \
            -o deployment/config-resolved.yaml \
            --verbose

      - name: Deploy application
        run: |
          docker-compose -f deployment/docker-compose.yml \
            --env-file deployment/config-resolved.yaml \
            up -d

      - name: Cleanup resolved secrets
        if: always()
        run: rm -f deployment/config-resolved.yaml
```

--------------------------------

### Wrapper Script to Resolve and Start MCP Gateway

Source: https://context7.com/acedergren/oci-vault-mcp-resolver/llms.txt

Runs the MCP Gateway integration wrapper script to both resolve secrets and start the gateway in a single command. This simplifies the deployment process by combining resolution and service startup.

```bash
./mcp-with-vault --start
```

--------------------------------

### Configure Prometheus with OCI Vault Secrets

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

This example demonstrates how to configure Prometheus to use secrets stored in OCI Vault. It shows referencing secrets directly by their OCID for both configuration URLs and API keys. Ensure the OCI Vault OCIDs are correctly formatted and accessible.

```yaml
servers:
  prometheus:
    config:
      PROMETHEUS_URL: oci-vault://ocid1.vaultsecret.oc1.iad.amaaaaaxxxxxx
      API_KEY: oci-vault://ocid1.compartment.oc1..xxx/prometheus-api-key
```

--------------------------------

### GitHub Actions for Resolving OCI Vault Secrets

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

A snippet demonstrating how to integrate OCI Vault secret resolution into a GitHub Actions workflow. It pipes the MCP configuration through a Python script to resolve secrets before writing the updated configuration.

```yaml
- name: Resolve OCI Vault Secrets
  run: |
    docker mcp config read | \
      python3 oci_vault_resolver.py | \
      docker mcp config write
```

--------------------------------

### Remote Development with Claude Code (Shell)

Source: https://context7.com/acedergren/oci-vault-mcp-resolver/llms.txt

Demonstrates using the OCI Vault Resolver in a remote development scenario with Claude Code. It shows how to create an application configuration file with OCI Vault references, create a wrapper script to resolve secrets and start the application, and how Claude can interact with this setup for configuration updates.

```shell
# Scenario: Claude Code managing application configuration

# Step 1: Create app config with vault references
cat > app-config.yaml <<EOF
database:
  host: postgres.example.com
  port: 5432
  username: admin
  password: oci-vault://ocid1.compartment.oc1..xxx/db-password

api:
  endpoint: https://api.example.com
  key: oci-vault://ocid1.vaultsecret.oc1.iad.xxx
  rate_limit: 1000
EOF

# Step 2: Create wrapper script for Claude to use
cat > start-app.sh <<'EOF'
#!/bin/bash
set -e

echo "Resolving secrets from OCI Vault..."
python3 oci_vault_resolver.py \
    -i app-config.yaml \
    -o app-config-resolved.yaml \
    --verbose

echo "Starting application with resolved config..."
python app.py --config app-config-resolved.yaml

# Cleanup on exit
trap "rm -f app-config-resolved.yaml" EXIT
EOF

chmod +x start-app.sh

# Step 3: Claude can now run
./start-app.sh

# Claude can also update configs securely
# User: "Update the API key to use the new secret 'v2-api-key' from my compartment"
# Claude: Updates app-config.yaml, then runs start-app.sh
```

--------------------------------

### Integrate OCI Vault Resolver in GitLab CI (YAML)

Source: https://context7.com/acedergren/oci-vault-mcp-resolver/llms.txt

Example of integrating the OCI Vault Resolver into a GitLab CI pipeline. This includes setting up Python, installing dependencies, configuring OCI credentials, resolving secrets, deploying the application, and cleaning up temporary files.

```yaml
# GitLab CI example
deploy:
  stage: deploy
  image: python:3.10
  variables:
    OCI_CONFIG_FILE: /tmp/oci-config
  before_script:
    - pip install -r requirements.txt
    - echo "$OCI_CONFIG" > $OCI_CONFIG_FILE
    - chmod 600 $OCI_CONFIG_FILE
  script:
    - python3 oci_vault_resolver.py
        --config-file $OCI_CONFIG_FILE
        -i config.yaml
        -o config-resolved.yaml
    - ./deploy.sh config-resolved.yaml
  after_script:
    - rm -f config-resolved.yaml $OCI_CONFIG_FILE
```

--------------------------------

### mcp-with-vault Wrapper Script Usage

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/API_REFERENCE.md

Shows examples of using the `mcp-with-vault` wrapper script, designed for seamless integration with Docker MCP Gateway. This script simplifies the process of resolving OCI Vault secrets and applying them. It supports options for setting cache TTL, enabling verbose logging, performing dry runs, and starting the MCP Gateway after configuration.

```bash
./mcp-with-vault [OPTIONS]
```

```bash
./mcp-with-vault --dry-run
```

```bash
./mcp-with-vault --start
```

```bash
./mcp-with-vault --ttl 7200 --verbose
```

--------------------------------

### Conventional Commit Message Examples (Bash)

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/CONTRIBUTING.md

This snippet provides examples of Git commit messages formatted according to the conventional commit specification, illustrating different types like 'feat', 'fix', 'docs', and 'refactor'.

```bash
# Format: <type>(<scope>): <description>

git commit -m "feat(resolver): add support for vault OCID format"
git commit -m "fix(cache): correct TTL calculation"
git commit -m "docs(readme): update installation instructions"
git commit -m "refactor(parser): simplify URL parsing logic"
```

--------------------------------

### Reference OCI Vault Secrets by Name

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

This example shows how to reference OCI Vault secrets using a combination of compartment/vault OCID and secret name. This approach offers better portability across different environments compared to using full secret OCIDs. Ensure the specified compartment/vault and secret names exist.

```yaml
servers:
  app:
    config:
      # Reference by compartment + secret name
      JWT_SECRET: oci-vault://ocid1.compartment.oc1..abc123/jwt-secret

      # Reference by vault + secret name
      ENCRYPTION_KEY: oci-vault://ocid1.vault.oc1.iad.xyz789/encryption-key
```

--------------------------------

### Pull Request Template Example (Markdown)

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/CONTRIBUTING.md

This is a markdown template for creating a pull request, outlining sections for description, type of change, testing performed, and a checklist to ensure all contribution guidelines are met.

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring
- [ ] Other (describe)

## Testing
- [ ] Tested manually with example config
- [ ] Tested with real OCI Vault secrets
- [ ] Verified caching behavior
- [ ] Checked error handling

## Checklist
- [ ] Code follows project style guidelines
- [ ] Documentation updated
- [ ] Examples work as expected
- [ ] Commit messages follow conventions
```

--------------------------------

### Resolve Secrets for Claude Desktop MCP Configuration

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

This example shows how to resolve secrets embedded within the Claude Desktop MCP configuration file (`mcp.json`). The secrets, stored as OCI Vault references in environment variables, are resolved and written to a new file (`mcp-resolved.json`). This resolved file can then be used by Claude Desktop.

```bash
# Resolve secrets from MCP config and save to a new file
cat ~/.config/claude-desktop/mcp.json | \
  python3 oci_vault_resolver.py > ~/.config/claude-desktop/mcp-resolved.json
```

--------------------------------

### Cron Job for Secret Refresh

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

An example cron job that periodically refreshes secrets by running the mcp-with-vault script. This ensures that any updated secrets in OCI Vault are applied regularly.

```bash
# Refresh secrets every hour
0 * * * * cd /home/alex/projects/oci-vault-mcp-resolver && ./mcp-with-vault
```

--------------------------------

### Basic Usage of OCI Vault Resolver

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/SDK_IMPLEMENTATION.md

Demonstrates how to run the OCI Vault Resolver script using basic command-line arguments for configuration and output files, including options for instance principals.

```bash
# Parallel resolution via OCI SDK (default)
python3 oci_vault_resolver.py -i config.yaml -o resolved.yaml

# With instance principals (for OCI VMs)
python3 oci_vault_resolver.py --instance-principals -i config.yaml -o resolved.yaml

# Or use wrapper
./mcp-with-vault
```

--------------------------------

### Verify Resolved Secrets

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Verifies that secrets have been successfully resolved in the MCP configuration by reading the config and filtering out lines containing the 'oci-vault://' prefix.

```bash
docker mcp config read | grep -v "oci-vault://"
```

--------------------------------

### Test Direct Secret Fetch by OCID

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Tests the OCI Vault Resolver by directly providing a secret OCID. The resolver will fetch the secret value from OCI Vault.

```bash
echo 'test: oci-vault://ocid1.vaultsecret.oc1.eu-frankfurt-1.amaaaaaahhxc6pyanshr7dq5klnc4mld6otcwzz3ijkkbbrwamk6kx7vb7wq' | \
  python3 oci_vault_resolver.py
```

--------------------------------

### Run OCI Vault Resolver with Custom Config File

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

Demonstrates how to specify a custom configuration file for the OCI Vault Resolver. This allows users to manage authentication credentials and settings outside the default `~/.oci/config` location, providing flexibility for different environments or security requirements.

```bash
# Custom config file
python3 oci_vault_resolver.py --config-file /path/to/config
```

--------------------------------

### Test Direct Secret Fetch by Compartment and Name

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Tests the OCI Vault Resolver by providing a compartment OCID and a secret name. The resolver will look up the secret within the specified compartment.

```bash
echo 'test: oci-vault://ocid1.compartment.oc1..aaaaaaaarekfofhmfup6d33agbnicuop2waas3ssdwdc7qjgencirdgvl3iq/mcp-test-secret' | \
  python3 oci_vault_resolver.py
```

--------------------------------

### Run OCI Vault Resolver with Default Config

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

Illustrates the basic command to run the OCI Vault Resolver using the default OCI configuration file, typically located at `~/.oci/config`. This is the most straightforward way to authenticate when the standard OCI configuration is already set up.

```bash
# Uses ~/.oci/config
python3 oci_vault_resolver.py -i config.yaml
```

--------------------------------

### Troubleshoot Secret Not Found by Name

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Helps in resolving issues where a secret cannot be found by its name. It includes listing secrets within a compartment to verify existence and checking for exact case-sensitive name matches.

```bash
# List secrets in compartment
oci vault secret list \
  --compartment-id YOUR_COMPARTMENT_ID \
  --all | jq '.data[] | {"name": ."secret-name", "id": .id}'

# Verify secret name matches exactly (case-sensitive)
```

--------------------------------

### Initialize OCI Vault Resolver in Python

Source: https://context7.com/acedergren/oci-vault-mcp-resolver/llms.txt

Demonstrates initializing the VaultResolver class with various authentication and caching configurations. Supports default settings, custom cache directories and TTLs, instance principal authentication, and custom OCI config files.

```python
from oci_vault_resolver import VaultResolver
from pathlib import Path

# Initialize with default settings (uses ~/.oci/config, 1 hour cache TTL)
resolver = VaultResolver()

# Initialize with custom cache directory and TTL
resolver = VaultResolver(
    cache_dir=Path("/var/cache/secrets"),
    ttl=7200,  # 2 hours
    verbose=True
)

# Initialize with instance principals (for OCI compute instances)
resolver = VaultResolver(
    use_instance_principals=True,
    verbose=True
)

# Initialize with custom OCI config file and profile
resolver = VaultResolver(
    config_file="/path/to/oci/config",
    config_profile="PRODUCTION",
    ttl=3600,
    verbose=False
)
```

--------------------------------

### Configure Custom Cache TTL

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Sets a custom Time-To-Live (TTL) for cached secrets using the `mcp-with-vault` script. This allows control over how long secrets remain cached, balancing performance with freshness.

```bash
# 5 minutes (for frequently rotating secrets)
./mcp-with-vault --ttl 300

# 2 hours (for stable secrets)
./mcp-with-vault --ttl 7200
```

--------------------------------

### Add OCI Vault References to MCP Config

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Demonstrates how to add OCI Vault secret references to the MCP configuration file. Supports both direct OCID and compartment+name formats. The configuration can then be applied using `docker mcp config write`.

```yaml
servers:
  prometheus:
    config:
      PROMETHEUS_URL: http://localhost:9090
      # Add your secret here
      API_KEY: oci-vault://ocid1.compartment.oc1..xxx/your-secret-name
```

--------------------------------

### Authentication with Instance Principals

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/SDK_IMPLEMENTATION.md

Illustrates how to use the OCI Vault Resolver with instance principals for authentication, which is suitable for OCI compute instances and does not require a config file.

```bash
# Automatic authentication on OCI compute instances
python3 oci_vault_resolver.py --instance-principals -i config.yaml

# No config file needed!
# Perfect for production deployments on OCI VMs
```

--------------------------------

### Update Existing Secret in OCI Vault

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Updates an existing secret in OCI Vault with a new base64 encoded value. It requires the Secret OCID and the new secret value. After updating, it clears the local cache to ensure the latest value is fetched.

```bash
SECRET_OCID="ocid1.vaultsecret..."
NEW_VALUE="updated-secret-value"

oci vault secret update-base64 \
  --secret-id "$SECRET_OCID" \
  --secret-content-content "$(echo -n "$NEW_VALUE" | base64)"

# Clear cache to force fresh fetch
rm -rf ~/.cache/oci-vault-mcp/
```

--------------------------------

### Python Extension Points for Custom Cache and Secret Providers

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/ARCHITECTURE.md

Demonstrates how to extend the functionality of the resolver by implementing custom cache backends (e.g., Redis) and secret providers (e.g., AWS Secrets Manager). These extensions allow for greater flexibility in managing where and how secrets are stored and retrieved.

```python
# Custom cache backend
class RedisCacheBackend(CacheBackend):
    def get(self, key: str) -> Optional[str]:
        return redis_client.get(key)

    def set(self, key: str, value: str, ttl: int):
        redis_client.setex(key, ttl, value)

# Custom secret provider
class AWSSecretsProvider(SecretProvider):
    def fetch_secret(self, secret_id: str) -> str:
        return secrets_manager.get_secret_value(secret_id)
```

--------------------------------

### Manually Resolve Secrets

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Manually resolves OCI Vault secrets from the MCP configuration using the Python resolver script. This involves piping the output of `docker mcp config read` to the resolver and then piping its output to `docker mcp config write`.

```bash
docker mcp config read | \
  python3 ~/projects/oci-vault-mcp-resolver/oci_vault_resolver.py | \
  docker mcp config write
```

--------------------------------

### Gitignore Resolved Configuration Files

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

This snippet shows recommended entries for a `.gitignore` file to prevent accidentally committing resolved configuration files, which contain sensitive secret values. It ensures that only the templates with vault references are version controlled.

```gitignore
# Ignore resolved configuration files containing actual secrets
*.resolved.yaml
config/*-resolved.yaml
```

--------------------------------

### Create a New Secret in OCI Vault

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/QUICKSTART.md

Demonstrates how to create a new secret in Oracle Cloud Infrastructure Vault using the OCI CLI. This involves setting compartment, vault, and key OCIDs, along with the secret name, value, and description. The secret value must be base64 encoded.

```bash
# Set variables
COMPARTMENT_ID="ocid1.compartment.oc1..aaaaaaaarekfofhmfup6d33agbnicuop2waas3ssdwdc7qjgencirdgvl3iq"
VAULT_ID="ocid1.vault.oc1.eu-frankfurt-1.bfpizfqyaacmg.abtheljtdamq6fvmwn4vzjcuprq"
KEY_ID="ocid1.key.oc1.eu-frankfurt-1.bfpizfqyaacmg.abtheljssy4ropepz7w7clogsnu3riy4wb6vk2d5u65zsm526dqtllucukaq"

# Create secret
SECRET_VALUE="your-secret-value-here"
SECRET_NAME="your-secret-name"

oci vault secret create-base64 \
  --compartment-id "$COMPARTMENT_ID" \
  --secret-name "$SECRET_NAME" \
  --vault-id "$VAULT_ID" \
  --key-id "$KEY_ID" \
  --secret-content-content "$(echo -n "$SECRET_VALUE" | base64)" \
  --description "Description of your secret"
```

--------------------------------

### Run oci_vault_resolver with Instance Principals Authentication

Source: https://context7.com/acedergren/oci-vault-mcp-resolver/llms.txt

Executes the oci_vault_resolver script using instance principals for authentication. This method is suitable for OCI compute instances and does not require a separate configuration file. Secrets are resolved and saved to the output file.

```bash
python3 oci_vault_resolver.py \
    --instance-principals \
    -i config.yaml \
    -o resolved.yaml
```

--------------------------------

### Initialize VaultResolver in Python

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/API_REFERENCE.md

Demonstrates how to initialize the VaultResolver class with default and custom parameters. The constructor accepts cache directory, time-to-live for cache, and a verbose logging flag.

```python
from oci_vault_resolver import VaultResolver
from pathlib import Path

# Default settings
resolver = VaultResolver()

# Custom cache directory and TTL
resolver = VaultResolver(
    cache_dir=Path("/custom/cache"),
    ttl=7200,  # 2 hours
    verbose=True
)
```

--------------------------------

### Parallel Secret Fetching with OCI Python SDK

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

Demonstrates concurrent fetching of multiple secrets from OCI Vault using Python's asyncio and the OCI SDK. This approach significantly speeds up secret retrieval compared to sequential methods, reducing latency for applications requiring numerous secrets. It requires the OCI SDK and a configured asynchronous event loop.

```python
import asyncio
from oci.secrets import SecretsClient
import oci

# Initialize once, reuse for all calls
config = oci.config.from_file()
secrets_client = SecretsClient(config)

# Parallel resolution using asyncio
async def fetch_all(vault_urls):
    tasks = [resolve_secret(url) for url in vault_urls]
    return await asyncio.gather(*tasks)

# Result: ~800ms for 10 secrets (parallel)
# vs ~7 seconds sequential CLI approach
```

--------------------------------

### Docker Compose Integration with Pre-start Hook

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/API_REFERENCE.md

Demonstrates how to configure a Docker Compose service for the MCP Gateway, using a resolved configuration file and a pre-start hook to apply vault secrets.

```yaml
services:
  mcp-gateway:
    image: mcp-gateway:latest
    volumes:
      - ./resolved-config.yaml:/config.yaml
    command: ["--config", "/config.yaml"]

# Pre-start hook
x-pre-start:
  command: ./mcp-with-vault
```

--------------------------------

### Verify IAM Permissions with OCI CLI

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

This bash command uses the OCI CLI to fetch details about your IAM user. This is a debugging step to help verify that your user has the necessary permissions to access secrets in OCI Vault. Compare the output with the required IAM policies.

```bash
oci iam user get --user-id <your-user-ocid>
```

--------------------------------

### Execute OCI Vault Resolver for Parallel Resolution

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

Shows the command-line execution of the OCI Vault Resolver script, optimized for parallel secret fetching. This command typically takes an input YAML configuration file with `oci-vault://` references and outputs a new file with the secrets resolved and injected.

```bash
# All secrets resolved concurrently
python3 oci_vault_resolver.py -i config.yaml -o resolved.yaml
```

--------------------------------

### Wrapper Script with Instance Principals Authentication

Source: https://context7.com/acedergren/oci-vault-mcp-resolver/llms.txt

Runs the MCP Gateway integration wrapper script using instance principals for authentication. This is intended for use on OCI compute instances where direct authentication to OCI services is configured.

```bash
./mcp-with-vault --instance-principals
```

--------------------------------

### Command-Line Usage

Source: https://context7.com/acedergren/oci-vault-mcp-resolver/llms.txt

Process configuration files or stdin/stdout streams using the resolver from the command line. Supports input and output file specifications and verbose logging.

```APIDOC
## Command-Line Usage

### Description
Process configuration files through stdin/stdout pipeline or file I/O.

### Method
`python3 oci_vault_resolver.py [options]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Basic usage: resolve secrets in config and output to stdout
docker mcp config read | python3 oci_vault_resolver.py | docker mcp config write

# Read from file, write to file
python3 oci_vault_resolver.py -i config.yaml -o resolved-config.yaml

# Enable verbose logging to stderr
python3 oci_vault_resolver.py -i config.yaml --verbose 2>&1 | tee resolution.log
```

### Response
#### Success Response (200)
Output depends on the mode of operation (stdout or file output). Resolved configuration or logs.

#### Response Example
N/A (Command-line execution)
```

--------------------------------

### Optimizing Cache Time-To-Live (TTL)

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/SDK_IMPLEMENTATION.md

Demonstrates how to adjust the cache TTL for secrets using the command-line interface, allowing for shorter durations for frequently changing secrets and longer durations for static ones.

```bash
# Short TTL for frequently changing secrets
./mcp-with-vault --ttl 300  # 5 minutes

# Long TTL for static secrets
./mcp-with-vault --ttl 7200  # 2 hours
```

--------------------------------

### Set File Permissions for Resolved Configs

Source: https://github.com/acedergren/oci-vault-mcp-resolver/blob/master/README.md

This command demonstrates how to set restrictive file permissions (read/write only for the owner, `0600`) on resolved configuration files. This is a crucial security measure to protect the actual secret values from unauthorized access.

```bash
# Verify and set restrictive permissions on the resolved config file
chmod 600 config/app-resolved.yaml
```