# SubscriberAPI MCP Server

An MCP (Model Context Protocol) server that lets **GitHub Copilot CLI** query SFMC SubscriberAPI execution logs — health checks, email lookups, execution traces, and recent errors.

## Who is this for?

SFMC developers and engineers who want to troubleshoot SubscriberViaAPI issues from the terminal using natural language, for example:

- "Is the SubscriberAPI log endpoint healthy?"
- "Find recent errors for source `MyForm`."
- "Get the execution trace for FormRequestID `abc-123`."

## Prerequisites

- [Node.js](https://nodejs.org/) 18 or later
- [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli)
- SFMC log API endpoint URL and API key (from your team's CloudPage / API setup)

## Quick start

### 1. Clone the repo

```bash
git clone https://github.com/YOUR-ORG/subscriberapi-mcp.git
cd subscriberapi-mcp
```

> **Tip:** Clone to a folder **without spaces** in the path (e.g. `C:\dev\subscriberapi-mcp`) to avoid Windows path issues.

### 2. Install and build

```bash
npm run setup
```

### 3. Add your credentials

```bash
cp .env.example .env
```

Edit `.env` and set:

- `SFMC_LOG_ENDPOINT` — your SFMC execution log API URL
- `SFMC_LOG_API_KEY` — your API key

**Never commit `.env`.** It is already in `.gitignore`.

### 4. Use with GitHub Copilot CLI

This repo includes a **project-level** MCP config (`.mcp.json`) with a **relative path** — no machine-specific paths required.

From the cloned repo folder, start Copilot:

```bash
copilot
```

Copilot auto-loads `.mcp.json` when you work in this project. You should see `subscriberapi` with a green checkmark under MCP Servers.

### 5. Test it

Inside Copilot:

```
Use subscriberapi health_check and tell me the result.
```

Or from the shell (one-shot):

```bash
copilot -p "Call subscriberapi health_check" --allow-all-tools
```

## MCP tools

| Tool | Description |
|------|-------------|
| `health_check` | Check if the SFMC log endpoint is available |
| `get_executions_by_email` | Find executions by email (optional source, date range, limit) |
| `get_execution_trace` | Get full trace for a `formRequestId` |
| `get_recent_errors` | List recent errors (optional filters) |

## How configuration works

| File | Purpose |
|------|---------|
| `.mcp.json` | **Shared** Copilot MCP config (relative `dist/index.js`, no secrets) |
| `.env` | **Private** API credentials (each developer creates their own) |
| `~/.copilot/mcp-config.json` | Optional global Copilot MCP config (user-specific) |

**Recommended:** Rely on `.mcp.json` in the repo. Each developer only needs their own `.env`.

If you previously added `subscriberapi` to your global `~/.copilot/mcp-config.json` with an absolute path, remove it to avoid duplicates:

```bash
copilot mcp remove subscriberapi
```

## Optional: global install (any folder)

If you want `subscriberapi` available outside this repo, register it once from the cloned folder:

**Windows (PowerShell):**

```powershell
.\scripts\register-copilot-mcp.ps1
```

**macOS / Linux:**

```bash
./scripts/register-copilot-mcp.sh
```

These scripts read credentials from your `.env` and register an absolute path on **your** machine only.

## Development

```bash
npm run dev    # run TypeScript directly (tsx)
npm run build  # compile to dist/
npm start      # run compiled server
```

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Red X on `subscriberapi` | Run `npm run build` so `dist/index.js` exists |
| `Missing SFMC_LOG_ENDPOINT` | Create `.env` from `.env.example` |
| Path split at space (Windows) | Clone to a path without spaces, or use the register script |
| Permission denied in `-p` mode | Add `--allow-all-tools` |
| Duplicate `subscriberapi` servers | Run `copilot mcp remove subscriberapi` for the global entry |

## License

ISC