KeyVaultBridge-macOS

An implementation of the Model Context Protocol (MCP) server tailored specifically for anchoring and retrieving confidential API access strings utilizing the secure enclave provided by the macOS Keychain.

CRITICAL NOTICE: This software is strictly proprietary to the Apple macOS operating environment due to its reliance on the Keychain Services API. It is fundamentally incompatible with Windows or Linux distributions. Consult the security advisories for comprehensive details.

Conceptual Summary

KeyVaultBridge-macOS provides developers with a robust mechanism to safeguard API credentials inside the macOS Keychain while exposing them through a uniform MCP interface. Key advantages include:

• Robust Credential Sequestration: Credentials are never exposed in plaintext configuration files (e.g., .env) or source code repositories.
• Universal Project Access: The same secrets are readily available for utilization across any active development workspace.
• Natural Language Interaction: Facilitates credential management and retrieval through descriptive linguistic requests (particularly useful when interfacing with advanced language models like Claude).
• Direct AI Provisioning: Allows immediate and secure injection of necessary access tokens directly into your generative AI assistants upon request.

Rationale: Elevating Beyond Traditional Environment Files

Migrating from conventional .ENV file practices to KeyVaultBridge-macOS resolves several endemic development friction points:

1. Source Control Security Conflicts:
2. .ENV files necessitate explicit exclusion from version control systems (via .gitignore) to prevent leakage.
3. This exclusion fosters an opaque operational context, rendering critical configuration invisible to team members and integrated AI agents.

4. Onboarding new engineers often involves complex, error-prone manual setup of required environment variables.

5. Limitations in LLM Tooling Integration:

6. Security policies inherently prevent Large Language Models (like Claude) from directly accessing local filesystem configurations such as .ENV files.
7. Tasks requiring external API interaction often devolve into manual intervention loops.

8. KeyVaultBridge-macOS enables your AI collaborator to programmatically request necessary credentials through standard protocol invocations.

9. Inter-Project Configuration Homogeneity:

10. Relying on local files usually mandates redundant storage of identical API credentials across disparate project directories.
11. Changes to a master key require tedious, error-prone updates across numerous file instances.
12. KeyVaultBridge-macOS establishes a singular, authoritative storage repository accessible globally by authorized processes.

This architectural choice delivers superior security for sensitive assets without compromising the operational visibility and accessibility required by modern AI development toolchains.

Core Capabilities

• Encrypted, protected persistence of API access credentials within the macOS Keychain.
• A comprehensive suite of MCP endpoints for credential persistence, retrieval, enumeration, and erasure.
• A streamlined Command Line Interface (CLI) for direct, non-programmatic credential management.
• Support for both streaming standard I/O (stdio) and network-based (HTTP/SSE) transport protocols.
• Full interoperability with any client adhering to the Model Context Protocol specification.

Deployment Procedure

# Secure a local copy of the repository
git clone https://github.com/yourusername/servemyapi.git
cd servemyapi

# Install required dependencies
npm install

# Compile the application artifacts
npm run build

Operational Guide

Command-Line Utility (CLI)

KeyVaultBridge-macOS includes a command-line utility for expedient management actions executed directly within the terminal:

# Install the CLI tool suite globally for system access
npm run build
npm link

# Display inventory of all saved access strings
api-key list

# Fetch a specific credential by its assigned label
api-key get service_endpoint_token

# Commit a new credential string
api-key store service_endpoint_token xxxxx.yyyyy.zzzzz

# Purge a saved credential entry
api-key delete service_endpoint_token

# Request usage documentation
api-key help

Stdio Server Mode (Default MCP Transport)

This mode offers the simplest deployment path for MCP integration, optimal for desktop applications like Claude Desktop:

npm start

HTTP Endpoint Server

For environments demanding network-level access:

node dist/server.js

This initiates the service, typically bound to TCP port 3000 (or the value specified by the PORT environment variable).

Smithery Integration

KeyVaultBridge-macOS is accessible as a managed service endpoint via Smithery.

import { createTransport } from "@smithery/sdk/transport.js"

const transport = createTransport("https://server.smithery.ai/@Jktfe/servemyapi")

// Initialize MCP client
import { Client } from "@modelcontextprotocol/sdk/client/index.js"

const client = new Client({
    name: "Test Client Instance",
    version: "1.0.0"
})
await client.connect(transport)

// Execute server operations via the LLM application framework
const tools = await client.listTools()
console.log(`Discovered utilities: ${tools.map(t => t.name).join(", ")}`)

Refer to the Smithery API documentation for detailed interaction specifications.

MCP Client Configuration

This utility functions seamlessly with any client compliant with the MCP specification. Configuration templates are present in the examples subdirectory.

Configuration for Claude Desktop

To enable KeyVaultBridge-macOS within Claude Desktop:

1. Locate or generate the configuration file for Claude Desktop:
2. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Windows: %AppData%\Claude\claude_desktop_config.json

4. Augment the mcpServers section (reference examples/claude_desktop_config.json for structure): json { "mcpServers": { "keyVaultBridge": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/servemyapi/dist/index.js" ] } } }

5. Substitute /ABSOLUTE/PATH/TO/servemyapi with the actual directory path where the tool is installed.

6. Initiate a restart of the Claude Desktop application.

Configuration for Windsurf

To integrate KeyVaultBridge-macOS with Windsurf:

1. Open the Windsurf application interface and navigate to the System Settings panel.
2. Incorporate the server definition using the schema provided in examples/windsurf_config.json.
3. Ensure all specified file paths point correctly to your local installation directory.

Exposed MCP Functions

KeyVaultBridge-macOS exposes the following callable utilities:

store-api-key

Persists a specified access token into the local Keychain.

Parameters: - name: The unique identifier or label assigned to the credential. - key: The actual secret token string to be secured.

Example Invocation (via LLM prompt):

Employ keyVaultBridge-macOS to deposit my authentication string ABC123XYZ under the label "Primary Service Credential"

get-api-key

Retrieves an access token previously stored in the Keychain based on its label.

Parameters: - name: The designated identifier of the credential sought.

Example Invocation (via LLM prompt):

Using keyVaultBridge-macOS, fetch the credential marked as "Primary Service Credential"

delete-api-key

Removes a credential entry from the Keychain storage.

Parameters: - name: The identifier corresponding to the entry slated for deletion.

Example Invocation (via LLM prompt):

Instruct keyVaultBridge-macOS to erase the credential labeled "Primary Service Credential"

list-api-keys

Generates a comprehensive roster of all currently stored credential labels.

No input arguments required.

Example Invocation (via LLM prompt):

Ask keyVaultBridge-macOS to enumerate every saved access credential I possess

Security Considerations

• All secrets are maintained exclusively within the cryptographically secured macOS Keychain environment.
• Access privileges are strictly confined to the operating system account executing the process.
• Keychain access mandates user authentication.
• Plaintext storage or logging of sensitive keys is systematically prevented.

Future Development Trajectory

Anticipated enhancements for KeyVaultBridge-macOS include:

• Codebase Scrutiny Module: A utility designed to scan project source files for references to external endpoints, sensitive URLs, and configuration variables, subsequently proposing optimal Keychain storage labels. This permits developers to maintain typical .ENV workflows while ensuring credentials are simultaneously available to authorized LLMs and auxiliary tools.

• Platform Portability Investigation: Researching and implementing secure credential management techniques compatible with Windows and Linux environments to broaden the tool’s applicability.

• Framework Integration Packages: Developing streamlined modules for seamless integration with popular application frameworks (e.g., Next.js, Express).

• Graphical Key Administration Panel: Creation of a lightweight web interface for intuitive, visual management of stored credentials.

Contributions, feature requests, or roadmap suggestions are welcomed via GitHub Issues or Pull Requests.

Maintenance and Building

# Execute in development mode with live reloading features enabled
npm run dev

# Test the CLI functionality during active development
npm run cli list

# Execute code style and quality checks
npm run lint

# Generate production-ready optimized build artifacts
npm run build

Licensing

MIT