npm package: @kubedeck/kubebuddy-radar-mcp
Description: Model Context Protocol server for KubeBuddy Radar API - Query 286+ CNCF projects with AI agents
Author: KubeDeck
Latest version: 0.0.3

# KubeBuddy Radar MCP Server

> 🚧 **Work in Progress** - This MCP server is currently in active development. Features and tools are being tested and refined.

Model Context Protocol server for [KubeBuddy Radar](https://radar.kubebuddy.io) - Query 286+ CNCF projects, release notes, security tracking, and your personal dashboard with AI agents like Claude Desktop, Cursor, or Windsurf.

## What is this?

This TypeScript MCP server wraps the KubeBuddy Radar API so AI agents can:
- Search and discover CNCF projects
- Get latest release information with AI-parsed notes
- Track security vulnerabilities and CVEs
- Filter by category, CNCF status, and security releases
- Access your personal subscriptions and dashboard

Public tools are routed through Cloudflare cache for speed, while private tools use WordPress Application Passwords for authenticated access.

## Installation

### Prerequisites
- Node.js 18+ and npm
- A KubeBuddy Radar account (free tier available at [radar.kubebuddy.io](https://radar.kubebuddy.io))

> ⚠️ **Windows Users**: Direct installation from GitHub (`npm install -g github:KubeDeckio/kubebuddy-radar-mcp`) may fail with EPERM errors or missing TypeScript compiler. Use the local build method below.

### Option 1: Install from Local Build (Recommended)

```bash
git clone https://github.com/KubeDeckio/kubebuddy-radar-mcp.git
cd kubebuddy-radar-mcp
npm install
npm run build
npm pack
npm install -g kubebuddy-radar-mcp-0.0.1.tgz
```

### Option 2: Install from npm (when published)

```bash
npm install -g @kubedeck/kubebuddy-mcp-server
```

## Configuration

### Claude Desktop

Edit your Claude Desktop config file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "kubebuddy-radar": {
      "command": "node",
      "args": [
        "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\@kubedeck\\kubebuddy-mcp-server\\dist\\index.js"
      ]
    }
  }
}
```

**Note:** Replace `YOUR_USERNAME` with your Windows username. On macOS/Linux, the path will typically be `/usr/local/lib/node_modules/@kubedeck/kubebuddy-mcp-server/dist/index.js`.

Restart Claude Desktop, and you're ready to ask questions like:
- "What's the latest Kubernetes version?"
- "Show me recent security releases"
- "What are the most popular CNCF projects?"

If you prefer not to install globally, use `npx` to launch the MCP server on demand:

```
{
  "mcpServers": {
    "kubebuddy-radar": {
      "command": "npx",
      "args": [
        "-y",
        "@kubedeck/kubebuddy-mcp-server"
      ]
    }
  }
}
```
`npx -y` will download and run the scoped package automatically whenever Claude starts.

### Other AI Assistants

MCP support is expanding. Check the [official MCP documentation](https://modelcontextprotocol.io) for integration with:
- Cursor IDE
- Windsurf
- VS Code with GitHub Copilot (experimental)

## Available Tools

### Public Tools (No Authentication)

| Tool | Description |
|------|-------------|
| `search_projects` | Search 286+ CNCF projects by name, description, category, or CNCF status |
| `get_project_by_name` | Quick lookup by project name - finds the best match |
| `get_recent_releases` | Latest releases with filtering by category or security-only |
| `get_stats` | Platform statistics and CNCF project distribution |
| `get_project` | Detailed project information by ID |
| `get_project_releases` | Release history with AI-parsed notes and CVEs |
| `get_popular_projects` | Most subscribed projects ranked by popularity |

### Private Tools (Authentication Required)

| Tool | Description |
|------|-------------|
| `get_my_dashboard` | Your subscriptions, Pro status, and webhook settings |
| `get_my_subscriptions` | Detailed subscription list with configurations |

## Authentication

Private endpoints require your WordPress username and an Application Password:

1. Go to [Account → Developer API access](https://radar.kubebuddy.io/account/)
2. Create an Application Password
3. Use format: `username:app_password` when prompted by AI agent

## Example Queries

Once configured, ask your AI assistant:

**Security & Vulnerabilities:**
- "What are the latest security releases?"
- "Show me critical CVEs from this week"
- "Are there any security issues in the latest Kubernetes?"

**Version & Release Info:**
- "What's the latest ArgoCD version?"
- "Show me recent CI/CD tool releases"
- "What breaking changes are in the new Prometheus release?"

**Discovery:**
- "What are the CNCF graduated projects?"
- "Show me popular service mesh tools"
- "Find projects in the Networking category"

## Features

- 🔍 **Smart Search** - Server-side search with exact match prioritization
- 🏷️ **Category Filtering** - Filter by CI/CD, Networking, Storage, Security, Observability, etc.
- 🛡️ **Security Tracking** - CVE lists, severity levels, and security-only filtering
- 🎓 **CNCF Maturity Filtering** - Filter by graduated/incubating/sandbox status
- 🤖 **AI-Parsed Release Notes** - Every release includes AI-generated summaries
- ⚡ **Cloudflare Cached** - Public endpoints are cached for instant responses
- 🔐 **Secure Authentication** - WordPress Application Passwords for private data

## Documentation

- [Full Documentation](https://radar.kubebuddy.io/docs/mcp-server/)
- [API Reference](https://radar.kubebuddy.io/docs/api/)
- [Testing Guide](./TESTING.md)
- [UX Improvements](./UX-IMPROVEMENTS.md)

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js
```

## Releases

A GitHub Action named [kubebuddy-radar-mcp/.github/workflows/mcp-release.yml](./.github/workflows/mcp-release.yml) now builds, packs, and publishes the MCP server whenever someone publishes a release or triggers the workflow manually.

1. The workflow runs `npm ci`, `npm run build`, `npm pack`, and uploads the generated `kubebuddy-radar-mcp-*.tgz` artifact.
2. It publishes to `https://registry.npmjs.org` under `@kubedeck/kubebuddy-radar-mcp` using the `NPM_TOKEN` secret, so make sure the repository secret is set before releasing.
3. Trigger it manually with the **Run workflow** button on GitHub or by creating/publishing a release; the tarball will also be available as an artifact for download.

Update the `version` field in `package.json` and anywhere the tarball name is referenced before releasing so `npm pack` produces the correct filename.

## Troubleshooting

**Installation fails with EPERM errors?**
This is a Windows-specific issue. Use the local build method: clone the repo, run `npm install && npm run build && npm pack`, then `npm install -g kubebuddy-radar-mcp-0.0.1.tgz`.

**Server not responding?**
Verify the path in your config matches where npm installed the package (typically `%APPDATA%\Roaming\npm\node_modules\@kubedeck\kubebuddy-mcp-server\dist\index.js` on Windows). Restart your AI assistant after configuration changes.

**Schema validation errors?**
Make sure you're on the latest version. Run `npm run build` and restart your AI assistant.

**Wrong project IDs?**
Search results now explicitly show IDs in format "ProjectName (ID: 651)".

**Need help?**
Check the [testing guide](./TESTING.md) or open an issue on GitHub.

## License

MIT

## Links

- [KubeBuddy Radar](https://radar.kubebuddy.io)
- [MCP Documentation](https://modelcontextprotocol.io)
- [Report Issues](https://github.com/KubeDeckio/kubebuddy-radar-mcp/issues)