# CloudPulse MCP Server

> Cross-cloud infrastructure visibility for AI agents. Diagnose issues across **AWS**, **Vercel**, GCP, and Cloudflare without ever leaving your editor.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js ≥18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)

---

## Why CloudPulse?

| Pain point                                       | CloudPulse fix                                                 |
| ------------------------------------------------ | -------------------------------------------------------------- |
| Frontend error on Vercel → must open AWS console | `get_correlated_logs` merges both timelines automatically      |
| AI can't see if an SG blocks port 5432           | `diagnose_service_link` inspects the security group rules live |
| Hitting Lambda concurrency limits silently       | `check_resource_limits` warns at 80% usage                     |
| Topology unknown before debugging                | `list_cloud_topology` maps every active service in seconds     |

---

## Quick Start

### 1. Install / run with npx

```bash
npx cloudpulse-mcp
```

The server auto-detects credentials already present on your machine (AWS CLI, environment variables, etc.).

### 2. Configure your AI client

**Claude Desktop** – add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cloudpulse": {
      "command": "npx",
      "args": ["-y", "cloudpulse-mcp"],
      "env": {
        "VERCEL_TOKEN": "<your-vercel-token>",
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}
```

**Cursor** – add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "cloudpulse": {
      "command": "npx",
      "args": ["-y", "cloudpulse-mcp"],
      "env": {
        "VERCEL_TOKEN": "<your-vercel-token>",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}
```

**VS Code + GitHub Copilot (Agent Mode)** – requires VS Code 1.99+ and the GitHub Copilot extension.

First, build the project:

```bash
npm run build
```

Then create `.vscode/mcp.json` in this repository:

```json
{
  "servers": {
    "cloudpulse": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "env": {
        "VERCEL_TOKEN": "${env:VERCEL_TOKEN}",
        "AWS_REGION": "${env:AWS_REGION}",
        "AWS_PROFILE": "${env:AWS_PROFILE}"
      }
    }
  }
}
```

`${env:VAR}` reads from your shell environment — no secrets in source control.

To use: open **Copilot Chat**, switch to **Agent mode**, click **Select Tools** and enable the CloudPulse tools, then ask naturally:

```
Why can't my Vercel project reach AWS RDS instance "my-db"?
```

---

## Credentials & Security

CloudPulse follows a **read-only, no-storage** policy:

| Credential  | How to provide                                                                        |
| ----------- | ------------------------------------------------------------------------------------- |
| AWS         | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`, or `AWS_PROFILE`, or EC2 instance role |
| Vercel      | `VERCEL_TOKEN` (personal access token from vercel.com/account/tokens)                 |
| Vercel Team | `VERCEL_TEAM_ID` (optional)                                                           |
| GCP         | `GOOGLE_APPLICATION_CREDENTIALS`                                                      |
| Cloudflare  | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID`                                      |

> **No credentials are logged or stored.** All values are read from environment variables at call time.

---

## Available Tools

### `list_cloud_topology`

Scan all configured platforms and return a unified service map.

```
Input (all optional):
  platforms       – ["aws", "vercel"]  filter platforms
  aws_region      – "us-east-1"
```

### `get_correlated_logs`

Fetch and merge logs from Vercel + AWS CloudWatch into one timeline.

```
Input:
  start_time *    – ISO-8601 or epoch ms  e.g. "2024-06-01T10:00:00Z"
  end_time        – defaults to now
  trace_id        – filter by trace/request ID across all sources
  aws_log_group_prefix  – default "/aws/lambda"
  vercel_project  – project name or ID
  aws_region
```

### `diagnose_service_link`

Check why service A can't reach resource B.

```
Input:
  source_service *  – "vercel" | "lambda" | "ec2" | ...
  target_resource * – "<type>:<id>"  e.g. "aws-rds:my-db", "external-api:https://..."
  port              – auto-detected (5432 for RDS, 443 for APIs, ...)
  vercel_project
  aws_region
```

Checks performed:

- Vercel env vars contain a `DATABASE_URL` / `DB_URL`
- AWS Security Group allows inbound TCP on the required port
- External API HEAD reachability test

### `check_resource_limits`

Query quotas and flag resources nearing their limits.

```
Input (all optional):
  platforms        – filter platforms
  warn_threshold   – usage % to warn at (default 80)
  aws_region
```

---

## Roadmap

| Phase                | Status  | Scope                                                                    |
| -------------------- | ------- | ------------------------------------------------------------------------ |
| **1 – MVP**          | ✅ Done | Vercel + AWS (Lambda, RDS, CloudWatch, Security Groups, S3)              |
| **2 – Extend**       | ✅ Done | GCP Cloud Run + Cloud SQL + Logging; Cloudflare Workers + Pages; S3 CORS |
| **3 – Intelligence** | 🔜      | Pre-built diagnostic playbooks for CORS, 504 timeout, cold-start loops   |

---

## Development

```bash
git clone https://github.com/Galadriel-Tech-Solutions/cloudpulse-mcp
cd cloudpulse-mcp
npm install
npm run dev        # run from source with tsx
npm run build      # compile to dist/
```

### Project structure

```
src/
├── index.ts                     # MCP server + tool registration
├── types.ts                     # shared domain types
├── utils.ts                     # concurrency, formatting helpers
├── providers/
│   ├── aws/
│   │   ├── index.ts             # client factory + isAWSConfigured()
│   │   ├── cloudwatch.ts        # CloudWatch Logs
│   │   ├── lambda.ts            # Lambda function listing
│   │   ├── rds.ts               # RDS/Aurora instances & clusters
│   │   ├── ec2.ts               # Security Group inspection
│   │   ├── s3.ts                # S3 buckets + CORS checks
│   │   └── quotas.ts            # Service Quotas API
│   ├── gcp/
│   │   ├── index.ts             # isGCPConfigured() + resolveGCPProject()
│   │   ├── cloud-run.ts         # Cloud Run services
│   │   ├── cloud-sql.ts         # Cloud SQL instances (sqladmin v1beta4)
│   │   └── logging.ts           # Cloud Logging
│   ├── cloudflare/
│   │   └── index.ts             # Pages, Workers, Worker tail logs (WebSocket)
│   └── vercel/
│       └── index.ts             # Vercel REST API v9
└── tools/
    ├── list-cloud-topology.ts
    ├── get-correlated-logs.ts
    ├── diagnose-service-link.ts
    └── check-resource-limits.ts
```

### Adding a new cloud platform

1. Create `src/providers/<platform>/index.ts` exporting:
   - `is<Platform>Configured(): boolean`
   - Provider-specific data functions
2. Wire the functions into the relevant tools under `src/tools/`
3. Add the platform name to the `CloudPlatform` union in `src/types.ts`

---

## License

MIT © CloudPulse Contributors