<div align="center">
  <h1>CAI MCP Toolkit</h1>
  <p><b>Model Context Protocol tools for Cox Automotive</b></p>

  [![Tests](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/actions/workflows/test.yml/badge.svg)](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/actions/workflows/test.yml)
  [![Release](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/actions/workflows/release.yml/badge.svg)](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/actions/workflows/release.yml)
</div>

---

CAI MCP Toolkit extends AI assistants with specialized tools for Cox Automotive workflows. Connect your IDE to Rally, GitHub Enterprise, New Relic, Salesforce, and more through the Model Context Protocol.

## Choose Your Setup Guide

| Experience Level | Guide | Description |
|------------------|-------|-------------|
| **Comfortable with the command line** | [Windows Setup](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/windows/) / [macOS Setup](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/macOS/) | Jump straight into installation, configuration, and IDE setup. |
| **Prefer a guided, step-by-step setup** | [Getting Started Guide](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/getting-started/) | Everything explained from scratch -- no technical experience needed. |
| **Not sure where to start** | [Slack: #ai-mcp](https://cox.enterprise.slack.com/archives/C08T4DUNCQH) | Your team lead or manager can help determine the right path, or ask us on Slack. |

## Features

- **Extensive Tool Library** for Rally, GitHub, Salesforce, and more — plus 30+ hosted **remote MCP servers** (New Relic, Datadog, Splunk, PagerDuty, and more) and bundled MCPs for Jira, Figma, and Confluence
- **Multiple IDE Support** for VS Code, JetBrains IDEs, and Claude Code
- **Configurable** - enable only the tools you need via YAML configuration
- **Extensible** - add bundled, local, or remote MCP servers
- **Web UI** - browser-based interface for configuration and tool exploration
- **Self-Diagnosing** - built-in doctor command and rescue mode for troubleshooting

## Quick Install

### GUI Installer (Recommended)

Download and run the installer for your platform:

| Platform | Download | VS Code | VS Code Insiders |
|----------|----------|---------|------------------|
| **Windows x64** | [Download](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-installer-win-x64.exe) | [![Configure](https://img.shields.io/badge/VS_Code-Configure-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=cai-mcp&config=%7B%22command%22%3A%22cai-mcp.exe%22%2C%22args%22%3A%5B%22--config%22%2C%22%24%7Benv%3AUSERPROFILE%7D%5C%5C.caimcp%5C%5Cconfig.yaml%22%5D%7D) | [![Configure](https://img.shields.io/badge/Insiders-Configure-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=cai-mcp&config=%7B%22command%22%3A%22cai-mcp.exe%22%2C%22args%22%3A%5B%22--config%22%2C%22%24%7Benv%3AUSERPROFILE%7D%5C%5C.caimcp%5C%5Cconfig.yaml%22%5D%7D&quality=insiders) |
| **macOS Intel** | [Download](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-installer-mac-x64.zip) | [![Configure](https://img.shields.io/badge/VS_Code-Configure-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=cai-mcp&config=%7B%22command%22%3A%22cai-mcp%22%2C%22args%22%3A%5B%22--config%22%2C%22%24%7Benv%3AHOME%7D%2F.caimcp%2Fconfig.yaml%22%5D%7D) | [![Configure](https://img.shields.io/badge/Insiders-Configure-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=cai-mcp&config=%7B%22command%22%3A%22cai-mcp%22%2C%22args%22%3A%5B%22--config%22%2C%22%24%7Benv%3AHOME%7D%2F.caimcp%2Fconfig.yaml%22%5D%7D&quality=insiders) |
| **macOS Apple Silicon** | [Download](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-installer-mac-arm64.zip) | [![Configure](https://img.shields.io/badge/VS_Code-Configure-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=cai-mcp&config=%7B%22command%22%3A%22cai-mcp%22%2C%22args%22%3A%5B%22--config%22%2C%22%24%7Benv%3AHOME%7D%2F.caimcp%2Fconfig.yaml%22%5D%7D) | [![Configure](https://img.shields.io/badge/Insiders-Configure-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=cai-mcp&config=%7B%22command%22%3A%22cai-mcp%22%2C%22args%22%3A%5B%22--config%22%2C%22%24%7Benv%3AHOME%7D%2F.caimcp%2Fconfig.yaml%22%5D%7D&quality=insiders) |

> **macOS Users:** The installer is not yet notarized. See [macOS Security Warnings](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/troubleshooting/#macos-security-warnings) for workarounds.

### Command Line

For step-by-step installation instructions, see [macOS Setup](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/macOS/) or [Windows Setup](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/windows/).

```bash
# Verify installation
cai-mcp --version

# Generate configuration
cai-mcp generate-config

# Launch web UI for configuration
cai-mcp web
```

### Claude Desktop

Claude Desktop uses `.mcpb` manifest bundle files. Download the bundle for your platform and follow the [Claude Desktop setup guide](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/clients/claude/).

| Platform | Architecture | Download |
|----------|--------------|----------|
| Windows | x64 | [cai-mcp-windows-x64.mcpb](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-windows-x64.mcpb) |
| macOS | Intel (x64) | [cai-mcp-macos-x64.mcpb](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-macos-x64.mcpb) |
| macOS | Apple Silicon (arm64) | [cai-mcp-macos-arm64.mcpb](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-macos-arm64.mcpb) |

> **Note:** All releases including pre-release betas are available on the [Releases page](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest).

### Binary Downloads

For manual installation or headless/Linux systems, download the binary directly.

> **All releases:** Browse all versions including pre-release betas on the **[Releases page](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest)**.

| Platform | Architecture | Download |
|----------|--------------|----------|
| Linux | x64 | [cai-mcp-linux-x64](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-linux-x64) |
| Linux | arm64 | [cai-mcp-linux-arm64](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-linux-arm64) |
| macOS | x64 | [cai-mcp-macos-x64](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-macos-x64) |
| macOS | arm64 | [cai-mcp-macos-arm64](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-macos-arm64) |
| Windows | x64 | [cai-mcp-win-x64.exe](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/releases/latest/download/cai-mcp-win-x64.exe) |

## Quick Start

1. **Install** using the GUI installer above

2. **Configure your IDE** by clicking the "VS Code Configure" button, or see setup guides for:
   - [VS Code](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/clients/vs-code/)
   - [JetBrains IDEs](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/clients/jetbrains/)
   - [Claude Desktop & Claude Code](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/clients/claude/)

3. **Enable tools** by editing your config file (`~/.caimcp/config.yaml` on macOS/Linux, `%USERPROFILE%\.caimcp\config.yaml` on Windows):

   ```yaml
   tools:
     includeCategories:
       - 'Rally'
       - 'Github: Issues'
       - 'Github: Pulls'
       - 'Github: Repos'
       - 'Github: Search'
       - 'Web'
       - 'Utility'
     # Hosted remote MCP servers are opt-in and authenticate through a browser
     # sign-in on first use (not via local API keys):
     includeRemoteMCPs:
       - newrelic
       - splunk
   ```

4. **Restart your IDE** to load the MCP server

That's it! Ask your AI assistant to use Rally or GitHub tools. The first time you use a remote MCP (New Relic, Splunk, …) a browser window opens to sign you in through the gateway.

## What's Included

| Component | Description | Details |
|-----------|-------------|---------|
| **Tools** | Rally, GitHub, Salesforce, and more local tools | [Tool Reference](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/reference/tools/) |
| **Prompts** | Reusable prompt templates | [Prompt Reference](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/reference/prompts/) |
| **Resources** | MCP resources for logs and references | [Resource Reference](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/reference/resources/) |
| **Bundled MCPs** | Third-party MCP servers (Figma, Confluence, etc.) | [Bundled MCPs](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/blob/main/bundled/README.md) |
| **Remote MCPs** | Hosted MCP servers (New Relic, Datadog, Splunk, GitHub, Atlassian, Postman, and 25+ more) | [Remote MCPs](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/reference/remotes/) |

> **Note:** Most tools are disabled by default. Edit your configuration to enable the categories you need.

## Documentation

| Topic | Description |
|-------|-------------|
| **Getting Started** | |
| [Getting Started Guide](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/getting-started/) | Guided setup -- no technical experience needed |
| [macOS Setup](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/macOS/) | Full installation and IDE setup for macOS |
| [Windows Setup](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/windows/) | Full installation and IDE setup for Windows |
| **Configuration** | |
| [Configuration Guide](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/configuration/) | YAML config, tool filtering, MCP servers |
| [API Key Setup](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/quickstart/api-keys/) | Rally and local-tool tokens (remote-MCP credentials are entered at the gateway, not here) |
| **Reference** | |
| [CLI Commands](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/configuration/#cli-reference) | All available commands |
| [Troubleshooting](https://ghe.coxautoinc.com/pages/CAPT-Innovation-Lab/mcp-tools/troubleshooting/) | Doctor command, rescue mode, common issues |

## CLI Quick Reference

```bash
cai-mcp                     # Start MCP server (default)
cai-mcp web                 # Launch web configuration UI
cai-mcp list-tools          # List all available tools
cai-mcp list-tools --filtered  # List only enabled tools
cai-mcp doctor              # Diagnose configuration issues
cai-mcp update              # Check for and install updates
cai-mcp --help              # Show all commands
```

## Contributing

We welcome contributions! See the [Contributing Guide](CONTRIBUTING.md) for:

- Development setup
- Creating new tools
- Testing guidelines
- Git workflow and conventional commits

## Support

- **Slack:** [#ai-mcp](https://cox.enterprise.slack.com/archives/C08T4DUNCQH)
- **Issues:** [GitHub Issues](https://ghe.coxautoinc.com/CAPT-Innovation-Lab/mcp-tools/issues)

---

<div align="center">

![Contributors](docs/src/images/contributors.png)

</div>